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PREFACE 


The purpose of this manual is to introduce the Multics environment to 
applications programmers who have experience on another operating system but are 
new to Multics. 


It is very important that you understand exactly who this manual is for, 
and what assumptions this manual makes about its audience, before you begin to 
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The intended audience of this manual is applications programmers. It is 
assumed that you have programmed on some other system(s) and that you have some 
basic knowledge of at least one higher level language (COBOL, FORTRAN, PL/I, 
etc.). No attempt is made here to teach you how to program. This manual is 
only intended to show you how to do the things you know how to do on another 
system on Multics. 


As an applications programmer, you look at an operating system from the 
viewpoint of some programming language. This manual does not attempt to discuss 
the use of any particular language on Multics, but rather, concerns itself with 
those practices which are appropriate no matter which language you use. For 
information on specific languages you snoulid refer to the Language Users! 
Guides. The names of these guides are included in the list of useful manuals 
for new programmers given at the end of this preface. 


This manual assumes that you are registered on Multics, and that you know 
how to log in and use a terminal. It also assumes that you have some general 
familiarity with the fundamental concepts and facilities of the Multics system. 
This information is available in the following publications: 


Order No. CH24 
Order No. CH25 


Users' Introduction to Multics - Part 


New 
New Users' Introduction to Multics - Part 


[An 


You should feel comfortable with the use of segments, directories, text 
editors, access control, commands, and active functions. If you don't, you 
should review the manuals listed above, as no review of this material will be 
presented here. 


The information and specifications in this document are 
subject to change without notice. This document contains 
information about Honeywell products or services that may 
not be available outside the United States. Consult your 
Honeywell Marketing Representative. 
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Section 1 of this manual offers an overview of the Multics operating system 
in general terms, to give you some idea of why programming on Multics may be 
different from working on other systems. 


Section 2 offers a step-by-step approach to the essentials of programming 
on Multies. It shows you how to create, compile, execute, revise, and document 
your programs in this environment, how to manipulate your segments, and how to 
create storage system links. Sample terminal sessions are also included. 


Section 3 takes you one step further by showing you the uses of dynamic 
linking on Multics. 


Section 4 provides you with an introduction to Multics input/output 
processing, showing you how to use the terminal for I/O and how to begin using 
I/O commands. 


Section 5 discusses the use of a Multics debugging tool. 
Section 6 discusses the use of a Multics performance measurement tool. 


Section 7 explains the Multics absentee facility, which offers capabilities 
Similar to batch processing on other systems. 


Section 8 offers a reference to all of the Multics commands by function, 
including a brief description of each command. 


The appendixes of this manual contain material which is specific toa 
particular language, somewhat advanced, or useful only to certain users. 


Appendix A shows you how to use Multics to best advantage in PL/I 
programming. 


Appendix B offers a step-by-step explanation of a PL/I text editor program. 
(This is for people who are ready to begin systems programming work.) 


Appendix C briefly introduces you to various Multics subsystems. 


‘Appendix D shows you how to use the Edm text editor. 


The information presented here is a subset of that contained in the primary 
Multics reference document, the Multics Programmers' Manual (MPM). The MPM 
should be used as a reference to Multics once you have become familiar with the 
concepts covered in this introductory guide. The MPM consists of the following 
individual manuals: 


Reference Guide Order No. AGQ91 
Commands and Active Functions Order No. AG92 
Subroutines Order No. AG93 
Subsystem Writers' Guide Order No. AK92 
Peripheral Input/Output Order No. AX49 
Communications Input/Output Order No. CC92 
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Throughout this manual, references are made to the MPM Reference Guide, the 
MPM Commands and Active Functions, the MPM Subroutines, and the MPM Subsystem 


Writers' Guide manuals. For convenience, these references are as follows: 


MPM Reference Guide 

MPM Commands 

MPM Subroutines 

MPM Subsystem Writers' Guide 


Other Multics manuals of interest to new programmers are listed below. 


@ Languages: 
Multics APL Order No. AK95 
Multics Basic Order No. AM82 
Multics COBOL Users' Guide Order No. AS43 
Multics COBOL Reference Manual | Order No. AS44 
Multics FORTRAN Users' Guide | Order No. CC70 
Multics FORTRAN Reference Manual Order No. AT58 
Multics PL/I Language Specification Order No. AGQ4 
Multics PL/I Reference Manual Order No. AM83 

e Subsystems: 
Multics FAST Subsystem Users' Guide Order No. AU25 
Multics GCOS Environment Simulator Order No. ANO5 
Multics Graphics System Order No. AS4O 


Logical Inquiry and Update System 
Reference Manual Order No. AZ49 


Multics Relational Data Store (MRDS) 
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Reference Manual Order No. AW53 
Multics Report Program Generator 
Reference Manual Order No. CC69 
Multics Sort/Merge Order No. AW32 
WORDPRO Reference Guide Order No. AZ98 
@ Micellaneous: 


Multics Pocket Guide - Commands 
and Active Functions Order No. AW17 


Index to Multics Manuals Order No. AN50 


The Multics operating system is referred to inthis manual as either 
"Multics" or "the system". The Emacs, Qedx, Ted, and Edm text editors are 
referred to as "Emacs", "Qedx", "Ted", and "Edm" respectively. 
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SECTION 1 


THE MULTICS APPROACH 


The Multics approach is quite different from that of a traditional batch 
operating system. The intent of this section is to show you how Multics is 
different, by giving you a general overview of the system's "personality", then 
describing in more detail three of its major characteristics: segmented virtual 
memory, dynamic linking, and controlled sharing and security. As these 
characteristics are discussed, important concepts associated with each will be 
introduced and explained. Familiarity with these concepts will help you when 
you read later sections of this manual and begin to program on Multics. 


Multiecs is a large, powerful, well-established system, which is constantly 
being refined, and provides a wide range of commands, languages, and subsystems. 
Despite its size and complexity, Multics is easy to learn and use. It has been 
designed to serve a wide variety and number of users, all cooperating and sharing 
resources. Multics offers its users the following advantages: 


e support for online usage: Multics has been designed to support online 
processing as well as batch processing. You can accomplish all of 
your programming tasks as either an interactive (online) user or an 
absentee (batch) user. Applications, debugging tools, data base 
management facilities, administrative tools and utilities are all 
accessible online. In one terminal session, you can write, compile, 
execute and debug your program. (See "Sample Terminal Sessions" in 
Section 2, and "Probe" in Section 5.) 


e consistent user interface: A great deal of thought has gone into 
making similar parts of Multics work in similar ways. For example, 
common control arguments such as -all and -brief are used with many 
different commands, and in each case, the control argument performs a 
similar function. In addition, all parts of the system have been 
designed to work together. 


s uniformity of control language: Batch processing on Multics is supported 
by the absentee facility (described in Section 7). An absentee job is 
processed like an interactive terminal session; it's directed by the 
same language as that used for interactive jobs. In other words, no 
special job control language (JCL) is ever required on Multics. The 
system commands and routines provide the logical branching, conditional 
execution, input/output control, and file system specifications necessary 
to direct any job. 


ease of use: On Multics, users are not asked to give information or 
make decisions ahead of time. There are many examples of this. You 
don't have to know or specify either a segment's size or its location 
to use it. You don't have to make your need for tape drives and 
Similar resources known in advance. Intelligent defaults mean that 
you need not create a correspondence between a file and an I/0 name. 
Dynamic linking (described later in this section) means that you need 
not name or prefetch programs you want to execute. You can set up a 
temporary working array for your PL/I or FORTRAN program in its own 
segment, without specifying how much space you need or worrying that 
the array will get too big. You will find that this lack of required 
prespecification greatly simplifies your use of the system. 
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SEGMENTED VIRTUAL MEMORY 


The most significant difference between the Multics programming environment 
and that of most other contemporary computer programming systems lies in its 
approach to addressing online storage. Most computer systems have two sharply 
distinct environments: a resident file storage system in which programs are 
created, and translated programs and data are stored; and an execution environment 
consisting of a processor and a "core image", which contains the instructions 
and data for the processor. Supervisor procedures provide subroutines for physically 
moving copies of programs and data back and forth between the two environments. 


In Multics, there is one conceptual memory, which is known as the virtual 
memory. The traditional distinction between secondary storage and main memory 
has no meaning, because a single infinitely large memory is simulated by the 
software, with data stored in finite segments which appear to be in memory at 
all times. Figure 1-1 illustrates this difference between a traditional system 
and the Multics virtual memory. 


With the line between the two traditional environments deliberately blurred, 
program construction on Multics is simplified: most programs need only be cognizant 
of one environment instead of two. This blending of the two environments is 
accomplished by extending the processor/core image environment. In Multics, 
your share of the processor is termed a process, and your core image is abstracted 
into what is called an address space. In a sense, each segment is a core image, 
and your process can have lots of them. 


The easiest way to think about the terms process and address space is to 
imagine your process as a private computer and your address space as a private 
memory for your process to work in. (See "Process, Address Space, and Execution 
Point" next in this section.) 


Another important difference between the Multics environment and that of 
most other systems is that an address in Multiecs has two parts: a segment 
identifier and a location, or offset, within the segment. 


Traditional Address 


Offset Multics Address 


(See "Segments and Addressing" later in this section.) 
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Figure 1-1. Traditional System vs. Multics Virtual Memory 
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Process, Address Space, and Execution Point 


When you log in to the system, you are allocated system resources in an 
environment known as a process. A process consists of a collection of segments 
called an address space, over which a single execution point is free to roam 
(i.e., to fetch instructions and make data references). 


A process executes programs on your behalf, either directly in response to 
your instructions or automatically as part of supporting the programs you invoke 
directly. The programs executed on your behalf and the data they reference make 
up your address space, and that address space combined with the action of executing 
those programs make up your process. Your execution point is whatever is executing 
at any moment. 


Space within the virtual memory is dynamically assigned to your address 
space. Its contents are a function of the sequence of instructions that are 
processed between the time you log in and the time you log out, and thus it 
dynamically shrinks and grows as necessary. Your address space is different 
from the usual core image in that it is larger and it is segmented. A segment 
may be of any size from 0 to 255K, and an address space may have a large number 
of segments (typically about 200). Usually, each separately translated program 
resides in a different segment; collections of data which are large enough to be 
worthy of a separate name are placed in a segment by themselves. The system 
assigns attributes (access control and length, for example) to each of these 
segments based on their logical use. There is a distinct address space for each 
user who is logged in, even though many users may share the very same segments 
in their address spaces. 


Your process is created when you log in, and destroyed when you log out, 
when you request a new process with the new_proc command, or when some kinds of 
errors occur. You may view your process as if all system resources are dedicated 
to it alone--as if you have a processor all to yourself--when in reality, all 
resources are being shared among many processes. Not only are there other interactive 
processes running, there are also absentee processes running as "background" to 
the interactive ones, and there are various daemon processes running, which are 
associated with the normal operation of the system and not connected to any 
user. All of these processes are continually cooperating and competing for 
processor time and main storage resources. The processor is multiplexed between 
processes according to rules defined for the system as a whole, with the object 
of sharing resources in an equitable manner. 


Processes can share with each other, and this sharing is of two types. 
First, any references to a segment by more than one process are references to 
the same segment. Second, a large part of the address space in all processes is 
identical, because the parts of the system shared by all users are given segment 
numbers (described below) that are the same forall processes. Figure 1~2 illustrates 
this sharing of segments. 


You should remember that each process's virtual memory is private to it. 
This means that changes made to one process's virtual memory assignments do not 
affect those of other processes. In addition, when a segment is being shared, 
it means that multiple users may not only read the segment, but also write it. 
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Figure 1-2. Processes Sharing a Segment 


1-5 AG90-03 


Segments and Addressing 


It's important to understand that a Multics segment is not a file. A 
segment can be addressed directly, like memory. It doesn't have to be read or 
written record by record like a file on other systems. On Multics, everything 
is in a segment: 


program source code 
program object code 
data files 
mail boxes 
work areas 


temporary storage 
exec coms 


There are two main reasons why segments are used in Multics. The first is 
that they make it possible for all your process's programs and data to be easily 
and directly addressable. The second is that they make it possible to protect 
and share programs and data by controlling access at the hardware level. (For 
more on this, see "Controlled Sharing and Security" later in this section.) 


The segment is often described as the basic unit of storage in Multics 
because all locating (addressing) of data in the system is done in terms of 
segments. The physical movement of information between main memory and secondary 
storage is fully automatic in Multics (it is done by the paging mechanism). The 
usual complex combination of file access methods and job control language which 
you are probably used to is replaced by a simple two-dimensional addressing 
scheme. This scheme involves the user-assigned symbolic name of the segment 
(its pathname), and the address of the desired item within the segment. Even 
relative addresses are usually given in symbolic terms through the data description 
facilities of the language you're using. Thus, each segment appears to its user 
as independent memory, symbolically located. Segments don't have to be in specific 
storage locations. They can be relocated anywhere in memory and grow and shrink 
as need be. 
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References to any portion of your address space consist of a segment name 
and a location within the segment; all addresses are interpreted as offsets 
within segments. To increase the efficiency of a storage reference, a segment 
number becomes associated with a segment name when the segment is initiated 
(added to your process's address space). A segment is said to be known to a 
process when it has been uniquely associated with a segment number in that 
process. The segment number is a temporary alias for the segment name, which is 
more easily translated into a storage address by the hardware. When you write: 


<symbolic name> | [symbolic_offset] 


the hardware uses: 


<segment number> | Loffset_number] 

The association between a segment name and a segment number is retained until 
the segment is terminated (removed from your process's address space). If it is 
terminated and initiated again, the number will be different. (See the discussion 
of initiating and terminating segments in Section 3.) Thus, every address or 
pointer is a pair of numbers: the segment number and the offset within the 
segment. This pair of numbers forming an address represents the coordinate of a 
location in the two-dimensional address space. See Figure 1-3 for a graphic 
representation of a two-dimensional address space. See Figure 1-4 for an 
illustration of the life of a segment. 


A program can create a segment by issuing a call to the system specifying 
the symbolic name as an argument. Different users can incorporate the same 
segment into their programs just by specifying its name. (A program need not 
copy a segment to use it.) A program can address any item within a segment 
using "segment, 1" where segment is the symbolic name of the segment and 1 is 
the location of the desired item within the segment. The ALM (Multics assembly 
language) instruction shown below illustrates a symbolic reference to location 
"x" in segment "data": 


lda data$x 


For more information on the Multics virtual memory, see the MPM Reference 
Guide. 


DYNAMIC LINKING 


Many programs make calls to external subroutines or use external variables. 
On most systems, these external references are resolved during loading or linkage 
editing. When the program is loaded into memory, external subroutines are loaded 
from libraries or user data sets, and storage is allocated for external variables. 
On Multics, external references are resolved when the program runs; i.e., the 
point at which something is used is the point at which it is found. This means 
that a compiled program on Multiecs is directly executable. Segmentation is what 
makes this possible - it gives each segment a "zero" location, so no relocation 
is necessary. 
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SUPERVISOR USER PROGRAMS, DATA, COMMANDS 
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Figure 1-3. Two-Dimensional Address Space 
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Note 1. 


Note 2. 


create 
initiate; per process 


(activate) 


— 


page 1 in memory 


has has 
exists segment page 
number table 


pages 2 and 4 in memory 


» (deactivate) 


terminate 


delete 


Figure 1-4. The Life of a Segment 
Events in parentheses are not user visible. 


Segments are automatically divided by the hardware into storage units 
known as pages, with a fixed size of 1024 words. (One word is equal 
to 36 bits or Q-bit bytes.) 


1-9 AG90-03 


Dynamic linking is accomplished by having the compiler leave in the object 
code of a compiled program an indirect word with a "fault tag" which, if used in 
an indirect address reference, causes a linkage fault to the dynamic linker. 
The linker inspects the location causing the fault, and from pointers found 
there, locates the symbolic name of the program being called or the data segment 
being referenced. It then locates the appropriate segment, maps it into the 
current address space, and replaces the indirect word with a new one containing 
the address of the program or data entry point, so that future references will 
not cause a linkage fault. When the system comes across an unresolved reference, 
it uses what are known as search rules (described in Section 3) to find the 
needed segment and establish the necessary link. This process is known as snapping 
a link. To see how the linkage fault caused by the ALM instruction mentioned 
previously would be resolved, refer to Figure 1-5. 


With dynamic linking, you don't pay the cost of resolving references (for 
example, calls to error routines) unless they are actually needed. If a subroutine 
is never called, it doesn't even have to exist, and the main program will still 
run correctly. An item in the file system has to be in your address space for 
you to use it, but it doesn't have to be copied and brought into memory before 
execution. The virtual memory guarantees that any item you reference is where 


the processor can address it directly. 


Dynamic linking simplifies your programming by totally eliminating the loading 
step. It also eliminates the need for a complicated job control language for 
retrieving, prelinking, and executing programs, and for defining and locating 
input/output files. 


For more information on dynamic linking, see the MPM Reference Guide. 


CONTROLLED SHARING AND SECURITY 


Multics permits controlled sharing of the operating system software and 
libraries, the language compilers, the data bases, and all user code and data. 
You can create links to other programs and data, give and revoke access, directly 
access any information in the system to which you have access, and share a 
single copy in core. 
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Figure 1-5. Resolving a Linkage Fault (Snapping a Link) 
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Access Control Lists 


One way of controlling the sharing and security of information is by using 
access control lists. ACLs, as you have already learned in the New Users' 
Introduction to Multics, define the access rights for each segment and directory. 
You can grant permission to use your segments and directories by individual 
user, by project, by instance (interactive/absentee), or by combinations of these. 
You can also grant different access to different users of the same segment. A 
good example of using ACLs is a compiler which resides in a segment that can be 
executed but not written. 


For more details on access control, see the MPM Reference Guide. 


Administrative Control 


Another kind of information control is administrative. Multics administration 
defines three levels of responsibility: system, project, and user. A system 
administrator allocates system resources among the projects on his system; a 
project administrator allocates project resources among the users on his project; 
a user can manage his own data through storage management and access controls. 


Your project administrator can define the environment of the users under 
his project. He can give you complete control in creating your own process, or 
he can limit the requests and commands available to you. He can determine the 


arrange things so you'll be automatically logged out if you exceed this limit. 
You won't be able to log in again until the next month begins or the limit is 
changed. He can also determine several other items, including whether a user 
can preempt others, specify his own directory, or have primary or standby status 
when logging in. 


You yourself also have flexibility in shaping your programming environment 
on Multics. A good example of this is the special command processor which 
allows you to make abbreviations for your frequently used commands (abbrev). 


For more information on Multics administrative features, refer to one of 
the manuals in the Multics Administrators' Manual (MAM) set: 


Project Administrator Order No. AK51 
Registration and Accounting Administrator Order No. AS68 
System Administrator Order No. AK50 
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SECTION 2 


PROGRAMMING ON MULTICS 


Programming on Multics is very different from programming on other systems. 
Many of the constraints and restrictions you may be used to are simply removed. 
The system provides high-level terminal control, data base management, 1/0 
interfaces, and data security. There is no need for overlays, chaining or partitions. 


This section explains how to write, compile and execute programs in the 
Multics environment. It also offers advice on revising and documenting programs, 
Manipulating segments, and creating storage system links. 


DESIGNING AND WRITING PROGRAMS 


Let's say you've been given specifications for a program which will compute 
the sum of three numbers. Obviously, this is not a realistic task for a computer, 
but it will provide us with a very simple example. 


Of course, the first thing you need to do is to develop a design for your 
program, be it a flow chart, a functional diagram, a hierarchy, or whatever. 
Once you have a good design, the next step is to decide which language you will 
write your program in. The following programming languages are available on 
Multics: 


® APL: A terse, powerful language, with strong data manipulation 
capabilities. 


@ BASIC: A simple language for beginners, which can perform string and 
arithmetic operations without much difficulty. 

@ cOBOL: A business oriented, high-level, English-like language with many 
string and arithmetic capabilities. 


@ FORTRAN: A high-level, scientific language designed mostly for arithmetic 
applications, with very limited character manipulation capabilities. 


@® PL/I: A very powerful, high-level language that offers almost total 
control over the operations of the program, and has many capabilities 
to manipulate characters and perform arithmetic operations. 


(ALM, the assembly language on Multiecs, is also available, but is not recommended 
for general use.) For this program, let's say you choose PL/I. The code for 
your program might look like this: 
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simple sum: proc options (main); 


/* this program computes the sum of three numbers set in the program, 
then prints the answer at the terminal */ 


declare 
sysprint file, terminal output ¥*/ 
first_no fixed binary first number */ 
second_no fixed binary second number ¥*/ 
third no fixed binary third number ¥*/ 
the sum fixed binary answer */ 


/* set the three numbers */ 
first_no = 123; 
second_no = 456; 
third_no = 789; 
/* add them up */ 
the sum = first_no + second_no + third_no; 


/*® print the answer ¥*/ 


put skip list ("The sum of the three numbers is:", the_sum); 
put skip; 


end simple sum; 


Notice the use of sysprint for the terminal output. For more information on 
this, see "Using the Terminal for I/0" in Section 4. 


Source Segments 


The next step is to create a segment containing your code. You can input 
your code by using any one of several text editors. Two editors you are already 
familiar with are Qedx and Emacs. Detailed information on these editors is 
available in the Qedx Users' Guide (Order No. CG4O) and the Emacs Users' Guide 
(Order No. CH27) respectively. Of special interest to programmers are the 
programming language modes available in Emacs. The FORTRAN, PL/I and ALM modes 
provide editing environments which facilitate the creation, formatting and debugging 
of programs written in these languages. 


Two more editors will be introduced here. One is Edm. This is the most 
basic Multics editor and is described in Appendix D of this manual. The other 
is Ted. Ted is a more advanced version of Qedx, which offers many advantages. 
These include more flexibility in addressing characters within a line, two types 
of input mode, regular and bulk, and more ways of manipulating buffers. Ted is 
a programmable editor, which means that you can write character manipulation 
programs in the Ted editor language. Other Ted features include sorting and 
tabbing capabilities, the ability to translate letters from upper to lower case 
and vice versa, and the ability to have lines fill and adjust. For more information 
on Ted, use the help command. 


The segment that your source code is stored in is called a source segment. 
Once your source segment is created, you should give it an entryname which 
follows the Multics convention for such names. This convention is to add a dot 
suffix to the end of the name indicating which language the program is written 
in. Thus, the form for a source segment entryname is: 
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program name.lang name 

A good name for your program would therefore be: 
simple sum.pl1 

Some other examples of program names are: 


ran_num_gen.basic 
payroll.cobol 
square_root.fortran 


(Remember that upper and lower case characters are not interchangeable on Multics. 
Thus, "payroll.cobol" and "Payroll.cobol" are two different names. See the MPM 
Reference Guide for more information on naming conventions.) 


You will probably find it useful to create several different directories 
for yourself, each containing a different sort of segment. For example, you 
could have one directory for the final (debugged) versions of your programs, one 
directory for the programs you are writing or revising, another directory for 
test data, etc. If you write programs in several different languages, you could 
also have directories for programs in each language. (Remember that your segments 
are not physically located in directories any more than you are physically in 
the phone book. When a segment is said to be "in" a directory, it means that 
the directory contains an entry for the segment.) 


COMPILING PROGRAMS 


Multics provides a compiler for each higher level language it supports. 
Compilers are system programs which translate source code into object code, 
machine level language that is executable by the hardware. The input to a 
compiler is a source segment. The output of a compiler is a corresponding 
object segment. (This discussion does not apply to APL, which is an interpreted 
language. There is no APL compiler and no APL object segment.) Your working 
directory is always assumed to be the location of the source segment you want to 
eompile, and the intended location of the object segment you want to create, 
unless you say otherwise. 


To execute a compiler, you invoke it as a command, with a command line 
which looks like this: 


language name path {-control_arguments} 


where language name is the name of the language your program is written in, path 
is the entry name of your source segment, and {-control arguments} are any of a 
number of optional control arguments you can supply to the compiler. Several of 
these control arguments instruct the compiler to create a listing segment in 
your directory. (No compile listing is produced by default.) This segment has 
the same entryname as your source segment, but with a suffix of "list" instead 
of "p11" or whatever. A listing segment contains a line-numbered list of your 
source program, plus information that is useful for understanding, debugging, 
and improving the performance of your program. 


The control arguments which produce a listing segment are: 
-list 
produces a complete source program listing including an assembly-like listing 


of the compiled program. Use of this control argument significantly increases 
compilation time and should be avoided whenever possible by using -map. 
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-map 
produces a partial source program listing of the compiled program which 
should contain sufficient information for most online debugging needs. 


Another useful control argument is: 


-table 

generates a full symbol table for use by symbolic debuggers. The symbol 
table is part of the symbol section of the object program (discussed later 
in this section) and consists of two parts: a statement table that gives 
the correspondence between source line numbers and object locations, and a 
name table that contains information about names actually referenced by the 
source program. This control argument usually causes the object segment to 
become significantly longer, so when the program is thoroughly debugged, it 
should be recompiled without -table. 


See the MPM Commands under the specifie compiler for detailed information on all 
of the control arguments and the information they provide. Also see the various 


Language Users' Guides 
So, your command line for compiling your program might look like this: 


! pli simple _sum.pli -map 


In this and all interactive examples in this manual, an exclamation point 
is used to indicate a line that you type at the terminal. You do not type the 
exclamation point, nor does Multics type it as a way of prompting you. It is 
strictly a typographical convention, to distinguish between typing done by you 
and typing done by Multics. 


In reality, you don't have to type the dot suffix component of your entryname. 
The compiler assumes that the input is a source segment, and will search your 
working directory (or whatever directory you're using) for the segment with the 
appropriate suffix. Thus: 


! pli simple _sum.plt1 
means exactly the same to the compiler as: 
! pl1 simple sum 
If your source code is clean and the compile is successful, an object 


segment is placed in the directory you're using, with the same entryname as your 
source segment, but stripped of the language name suffix: 


ran_num_gen.basic --------- > ran_num_ gen 
payroll.cobol  -+------- > payroll 
Square_root.fortran --------- 2 square_root 


So, if you execute this command line: 
! pl1 simple sum -map 

then you list your working directory, you'll see: 
simple sum 


simple_sum.pl1 
simple_sum.list 


Your listing segment, simple _sum.list, can be printed on your terminal 
with the print command, or printed on paper with the dprint command. Since 
listing segments take up a large amount of space, the sensible thing to do 
is to dprint the segment, then delete it: 
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If there are problems with your source code, the compiler will produce 
error messages.- The compiler can detect errors according to the definitions of 
the language involved. These include typing errors, syntax errors, and semantic 
errors. These messages are printed for you at your terminal. The format and 
details of error messages vary from compiler to compiler. The following is a 
sample PL/I error message: 


ERROR 158, SEVERITY 2 ONLINE 30 
A constant immediately follows the identifier "zilch" 
SOURCE: a = zilch 4; 


If your compile is taking a long time, you can issue a QUIT signal and take 
a look at your ready message. Since a ready message contains the amount of CPU 
time used since the last ready message, if the CPU times on your last two 
messages are different, you know your compilation is working. To resume it, 
type start. You can also use the progress (pg) command to get information on 
how a command's execution is going. To cheek on your compile of simple sum.pl1 
with the -map control argument, you would type: = 


! progress pll simple _sum -map 


The system would periodically type information about the pl1 command's progress 
in terms of CPU time, real time, and page faults. (A page fault occurs when a 
page of a referenced segment is not in memory.) See the MPM Commands for a 
detailed explanation. 


Object Segments 


As you may remember from the discussion of dynamic linking in Section 1, an 
object segment is an executable module. This is quite different from other 
systems, where the object module which is the output of the compiler cannot be 
executed until it has been through some kind of linkage editing to become a load 
module. On Multics, there is no such distinction between an object module and a 
load module. Thus, there is no need for you to determine in advance the absolute 
addresses of programs in memory, or give instructions for linking and calling 
programs or loading them. All compiled programs are ready to run. 


Most higher level languages supported by Multics compile into Multics standard 
object segments. These are divided into several sections. The first section is 
called the text section and contains the binary machine instructions that were 
translated from the source code and are executed by the processor. The next 
section is the definition section, which defines the names and locations of 
entry points present in the segment, and the names of external entry points used 
by the segment. An entry point is a symbolic offset within a segment. (See "A 
Naming Convention" in Section 3.) After the definition section comes the linkage 
section, which serves as a template of all virtual addresses for all external 
entry points used by the program. It contains per-process information used by 
the dynamic linker to resolve these external references. The next section is 
the static section, which contains data items to be allocated on a per-process 
basis. (This section may be included in the linkage section, and not exist as a 
separate section.) Then there is the symbol section, which contains information 
on all the variables declared in the program. The symbol section is always 
present in the object segment. If -table is specified when the program is 
compiled, then a symbol table is included in this section. Some compilers (e.g., 
pl1) support the -brief_table control argument, which produces a shorter symbol 
section. Finally there is the object map, which contains the lengths and offsets 
for each section of the object segment. Details about the format of object 
segments and what each section contains may be found in the MPM Subsystem Writers’ 
Guide. 
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Where the standards for the source language permit, all object segments 
produced by Multics are: 


e pure: the object segment contains no code that modifies itself during 
execution. Information about calls outside the segment is copied into 
a special segment, and all modifications are made to the copy. The 
same segment can be executed by more than one user. No copies of 
object segments are made on a per-user basis; there is one shared 
segment in the address space of all who use it. For example, even 
when multiple users are simultaneously compiling COBOL programs, only 
one copy of the COBOL compiler is in use. 


e recursive: the object segment can call itself. 


* in standard format: the calling protocols for object segments are the 
same irrespective of the higher-level language of origin. This means 
that a program in one language can call a program in another language. 
Programs can also access any data or file which can be described by 
data types supported by the particular language. 


EXECUTING PROGRAMS 


Now that you have an object segment, you are ready to try executing your 
program. To do this, all you have to do is type the name of your program from 
command level. The entryname is understood as a command--the system is instructed 
to find your program and execute it, just as when you type the name of a command 
(like list), the system is instructed to find the program by that name and 
execute it. Source and object segments are both permanent (they don't have to 
be copied to a special directory to be saved), so your program can be run over 
and over until you choose to delete it. 


Some Results of Execution 
e The program runs to normal termination and you get a ready message, 
indicating that execution was successful. 
r 10329" 320.350 
e The program pauses for input from your terminal. 


= The program halts because of a breakpoint you've put in it for debugging 
purposes. 


® The program runs to normal termination, but the output you get is 
wrong. 
© The program halts because you issue a QUIT signal, and the system 


responds with a ready message indicating a new command level: 


! QUIT 
r 10:40 0.1 497 level 2 


® The program halts because of an execution error. Examples of such 
errors are overflows, underflows, data conversions, and undefined 
references. The system prints an error message, then gives you a 
ready message indicating a new command level: 


Error: Exponent overflow by >udd>ProjA>MacSissle>bad_pgm}| 143 
(line 33) 

System handler for condition returns to command level 

r 10:38 0.185 98 level 2 
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The new command level means that you are again in a position to invoke 
commands. There are some special commands that can be put to appropriate use 
here, such as the release, start, program_interrupt, or probe commands. The 
release command returns you to the original command level--the work you were 
doing at the time of the interrupt is simply discarded. The start command 
resumes execution where it left off. The program interrupt command returns execution 
to a predetermined point from which to resume execution. For the use of the 
probe command see Section 5, "Debugging Tools." 


Multies will provide you with as specific an error message as possible. 
One common error that happens to almost everyone at some time or other is the 
following: 


Error: record quota_overflow condition by <program_name> 


This message means that you have run out of storage space in the system. The 
best way to fix this situation is to delete unneeded segments and type start. 
(For descriptions of other common error messages, see Multics Error Messages: 
Primer and Reference Manual, Order No. CH26.) 


REVISING AND DOCUMENTING PROGRAMS 


If you edit your program and recompile it, you may want to save the old 
object segment instead of replacing it with the new one. In the process of 
developing and testing new versions of a program, you may in fact end up with 
several versions, all of which you want to keep. Here are some ways you can do 
iG: 


s You can move the old object to another directory, using the move command: 
! move simple_sum obsolete_plil_obj>simple_ sum 


@ You can copy the faulty source (should you wish to save it as well) 
and give a new name to the edited version using the copy and rename 
commands: 


! copy simple _sum.pl1 obsolete _plil_source>simple_sum.pl1 
' rename simple sum.pl1 new_simple sum.pl1 


e You can change the name of the old object: 
! rename simple sum old_simple sum 


You need to be aware of certain dangers involved in renaming segments which are 
already known to your process. Renaming a segment doesn't change the association 
between the segment name and the segment number. So, if pgma calls pgmb, then 
you rename pgmb as badb, create a new pgmb, and run pgma again, when pgma calls 
pemb, it will end up with the old badb instead of the new pgmb. For more 
information on the association between segment names and segment numbers, see "A 
Note on Initiated Segments" in Section 3. 


If you ever get confused as to which version of your source program is 
which, you can use the compare_ascii (cpa) command, which compares ASCII segments 
and prints any differences. 


Remember that final versions of your programs should be correctly formatted 
to improve their readability. There are several Multics commands which can help 
you do this. For example, the indent (ind) command indents free-form PL/I source 
code according to a set of standard conventions. For another example, the 
format_cobol_source (feces) command converts free-form COBOL source programs to a 
fixed format. These commands also detect and report certain types of syntax 
errors, and can be used for pre-compile examinations. 
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Your final versions should also be well-documented. There are two kinds of 
documentation for programs. One is internal, and consists of a step-by-step 
description of what the program does. This sort of documentation is best created 
by the generous use of comments throughout your code. The other kind of documentation 
is external, and consists of a more general description of the programs purpose, 
design, and use. Writing info segments is an excellent way of creating this 
sort of documentation. (Remember that the information in an info segment is 
printed using the help command). 


Finally, all of your source and object segments should have the proper 
access set, so only the appropriate people can use them. 


SAMPLE TERMINAL SESSIONS 


Figure 2-1 displays the interaction between Multics and the user Karen 
MacSissle as she logs in and writes, compiles, and executes the simple sum program. 
MacSissle uses the Qedx editor to put the program online, the pli command to 
compile it, and the program name (without the language suffix) to execute it. 
Note that MacSissle does not have the usual ready message. She sets her message 
to "Karen is here" by using the general_ready (gr) command in her start_up.ec, 
the special exec_com that runs each time she logs in. (See the MPM Commands for 
information on the use of general ready.) 


In Figure 2-2, user Tom Smith is shown writing a program called times 2, 
which accepts an integer and prints the value of 2 times that integer. Smith 
takes advantage of the terminal for both input to and output from his program. 


A Note on Examples 


Because Multics is written mainly in PL/I, you may find that its runtime 
environment is somewhat oriented towards the convenience of PL/I programmers. 
Ways to take advantage of this orientation are presented in Appendix A, "Using 
Multies to Best Advantage". However, as mentioned in the preface, this manual 
is intended to be useful for all programmers. Although the majority of the 
examples are given in PL/I, there is no need to be discouraged if you aren't 
familiar with this language. Most of the examples are extremely simple. To see 
how you could write the same program in either PL/I, FORTRAN, or COBOL, see 
Section 4, "Using the Terminal for I/O". 


. 


ARCHIVING SEGMENTS 


Segments in Multics are assigned space in increments of pages (4096 characters). 
This can be very wasteful if you have many short files stored in the system. 
The archive (ac) command allows you to combine several segments into a single 
segment called an archive. Once in an archive, the individual segments are 
called components of the archive segment. Packing segments together in this way 
can produce significant savings in storage allocation and cost. 


By invoking the archive command with different arguments, you can manipulate 
the archive segment in a variety of ways. For example, in addition to creating 
your archive, you can also get a table of contents that names each component in 
the archive, extract one or more components from the archive, update and replace 
one or more components, and delete individual components. 
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er ee er ee ee 


login MacSissle 
Password: 


MacSissle ProjA logged in 03/18/81 0921.4 mst Wed from VIP7801 
terminal "none". 


Last login 03/18/81 0726.2 mst Wed from VIP7801 terminal "none". 
Karen is here 


gedx 
a 
simple sum: proc options (main); 


/* this program computes the sum of three numbers set in the progran, 
then prints the answer at the terminal */ 


declare 
sysprint file, /® the terminal output */ 
first_no fixed binary (17), /* the first number */ 
second no fixed binary (17), /* the second number */ 
third no fixed binary (17), /*® the third number */ 
the_sum fixed binary (17)3 /* the answer */ 
/® set the three numbers */ 
First no-=. 123% 
second no = 456; 
third no = 789; 
7® add them up ¥*/ 
the sum = first_no + second_no + third_no; 
/*® print the answer */ 


put skip list ("The sum of the three numbers is:", the_sum); 


put skip; 
end simple sum; 
\f 
w Simple _sum.pl1 
q 


Karen is here 
pl1 simple sum 
PL/I 

Karen is here 
simple sum 


The sum of the three numbers is: 1368 
Karen is here 


Figure 2-1. Sample Terminai Session #i 
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ee ee ee ee ee ee ee ee ee ee ee ee ee ee) 


login TSmith 
Password: 


TSmith ProjA logged in 06/07/79 0927.5 mst Tue from ASCII 
terminal "234", 
Last login 06/06/79 1259.8 mst Mon from ASCII terminal "234". 


A new PL/I compiler was installed; type: help pl1_new 
Rates for CPU usage have changed; type: help prices 
r 9:27 1.314 30 


qedx 

times 2: proc; 

declare (num,product) fixed bin(17); 

declare (sysin input, sysprint output) file; 
put list ("Enter integer"); 


put skip; 

get list (num); 

product = num*2; 

put skip list ("2 times your integer is:", product); 
put skip; 

close file (sysin), file (sysprint); 

end; 

Ae 


w times 2.pl1 
q 
r 9:40 4.875 62 


pli times 2 
PL/1 
r 9:41 2.906 272 


times 2 
Enter integer 
19 


2 times your integer is: 
r 9:43 0.231 50 


Figure 2-2. Sample Terminal Session #2 
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For more information about the archive command and its use, refer to the MPM 
Commands. 


BINDING SEGMENTS 


The Multics bind (bd) command is used to merge several separately compiled 
object segments into a singie executabie object segment called a bound segment. 
The binder is primarily an optimizer, which saves search time and link snapping. 
It resolves as many external references as it can in order to avoid the necessity 
cf resolving them at run time. These references are resolved without recourse 
to the search rules--the binder looks only in the programs that are being bound, 
and rejects any programs in which there are ambiguous external references. 


Binding offers the advantages of taking up less storage for the object 
code, decreasing execution time, and avoiding many linkage faults that would 
otherwise occur if the bound programs referenced each other from separate segments. 
Those programs that you call frequently and that are interrelated (ie, reference 
one another) should be bound to improve program efficiency. The segments must 
be archived before they are bound. 


For more information about the bind command, refer to the -MPM Commands. 
Also, the MPM Subsystem Writers' Guide provides information on the structure of 
bound segments. 


LINKS 


The word "link" is used for two separate things in Multics: an intersegment 
link and a storage system link. This can be confusing for beginners, but once 
you know the system, things are usually clear from their context. 


An intersegment link is an interprocedure reference, resolved by the linker. 
This kind of link is described in Section 3, "Dynamic Linking". 


A storage system link is essentially a "pointer" to a "target". This kind 
of link is described here. A storage system link is catalogued in a directory 
like a segment, but just gives the pathname of some other place in the directory 
hierarchy. The target of such a link is usually a segment, but it can also be a 
directory, or even another link. A storage system link enables you to access a 
segment located in some other portion of the directory hierarchy without actually 
making a copy of it, just as if it were catalogued in your own working directory. 
This is one of the ways in which Multiecs facilitates sharing. 


Multics allows you to create a link anywhere in the storage system as long 
as you have the proper access to the directory in which the link is to be 
placed. You invoke the link (1k) command to create a link and the unlink (ul) 
command to delete a link. (Refer to the MPM Commands.) To see a list of the 
links you have in your working directory, you can use the list command with the 
-link control argument. 
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SECTION 3 


DYNAMIC LINKING 


As the discussion of dynamic linking in Section 1 indicated, external references 
on Multics are resolved when a program is executed. When the system comes 
across an unresolved reference, it uses what are known as search rules to find 
the necessary segment and establish the link. The purpose of this section is to 
explain how the search rules operate, then to show you some of the uses of 
dynamic linking. 


A NAMING CONVENTION 


Due to a Pl1/I extension which is local to Multies, the "$" character is 
understood when it appears as part of an external name. afb is interpreted to 
mean segment a, entry point b. (Remember that an entry point is a symbolic 
offset within the segment. Refer to the discussion of two-dimensional addressing 
in Section 1.) Thus, hes $initiate, which will be discussed later in this section, 
is interpreted to mean segment hces_, entry point initiate. 


SEARCH RULES 


Let's suppose that you are writing a new version of the @edx Text Editor, 
and have a segment in your working directory named "qedx". If you type "qedx" 
on your terminal, you are instructing Multics to find the program named qedx and 
execute it. But which gedx do you want--yours or the system's? To make the 
situation a little bit more complicated, let's suppose that one of your coworkers 
is also writing a new version of Qedx, and has a segment in one of his directories 
named "qedx", to which you have access. You might want to run his program 
sometimes instead of yours or the system's. 


In each case, it's up to Multics to figure out which segment you want. The 
way Multics does this is by searching. To understand why Multics searches the 
way it does, you first need to know some of the assumptions it works under. 


Once you have invoked some program or accessed some data base, Multics 
assumes there is a good chance you will do so again. If the item is in your 
address space, that cuts down on the system overhead required to make a complete 
search for it a second or third time. So Multics keeps track of all the work 
you do after you login. It records your movement through the file system, 
noting each item it has located for you and putting these items in your address 
space. Multics also assumes that any time you use a reference name which you 
have already used, you mean the same item you meant the first time. (A reference 
name is a name used to identify a segment that has been made known by the user.) 
The name of the item and the information the system needs to find it are recorded 
in a table called the reference name table. Segments in this table are referred 
to as initiated segments. 


3-1 AG90-03 


The search rules are a list of directories which are searched in order 


until the desired segment is found. The standard search rules are: 


1. 


You 


initiated_segments 


Reference names for segments that have already been made known to a specific 
process are maintained by the system. A reference name is associated with 
a segment in one of four ways: 


ae use in a dynamically linked external program reference. 
b. use in an invocation of the initiate command. 
C. a call to hes $initiate, hes $initiate count, or hcs_$make_ seg with a 


nonnull character string supplied as the ref name argument. These 
hes _ entry points are described in the MPM Subroutines. 


di a call to hes_$make_ptr or hes _$make_entry (described in the MPM 
Subroutines). 


referencing dir 


The referencing directory contains the segment whose call or reference initiated 
the search. So, if pgma calls pgmb, and pgmb isn't in the reference name 
table, the system looks for pgmb in the directory where pgma resides. 


working dir 


The working directory is the one associated with you at the time of the 
search. This may be any directory established as the working directory by 
either the change wdir command or the change _wdir_ subroutine (described in 
the MPM Commands and MPM Subroutines respectively). The initial working 
directory is your home directory. 


system libraries 
The system libraries are searched in the following order: 


>system_library_standard 
This library contains standard system service modules, i.e., most system 
commands and subroutines. 


>system_library unbundled 
This library contains Multics Separately Priced Software. 


>system_library_ 1 
This library contains a small set of subroutines that are reloaded 
each time the system is reinitialized. 


>system library tools 
This library contains software primarily of interest to. system 
programmers. 


>system_library_auth_maintained 


This library contains user maintained and installation maintained 
programs. 


can see what your process's current search rules are by using the 


print_search_rules (psr) command: 
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psr 
initiated segments 
referencing dir 
working dir 


>system library standard 
>system_ library unbundled 
>system_library_1 

>system library tools 
>system library auth maint 


Note that, according to these search rules, if you have in your working 
directory a program with the same name as a system command or subroutine, your 
program will be used rather than the system's. Don't give your programs the 
same names as those of system programs, unless you really are trying to replace 
them. Here is an example of the troubie you can get into when you duplicate the 
name of a system program. Suppose you have a program of your own which creates 
an output file and you name the file "list." If you run your program, then try 
to list your working directory using the list command, you will get a message 
like this: 


command processor_: Linkage section not found. list 


The system thinks you are trying to run your output file, list, as a program! 


You can modify your search rules by using the add _search_rules (asr), 
delete search rules (dsr), and set_search_rules (ssr) commands, described in the 
MPM Commands. In addition, your system administrator can modify the default 
Search rules described above for all users at: your site. 


Thus, the first time you invoke a program after login, the system begins 
its search for the segment by looking in the reference name table. The search 
fails there, so it continues through the list of directories in the search rules 
until the segment is found or all the directories have been searched. Subsequent 
invocations of the same program are much faster, because the system finds the 
program right away in the reference name table. 


ee  ———— 


If your program named x references a program named y by means of a call or 
function reference, a dynamic link is established between x and y so that all 
subsequent references to y by x are accomplished by using the segment number 
(the alias for the segment name discussed in Section 1). If you change to a new 
working directory, and execute a program named z that calls a program in this 
new directory named y, the system will establish a dynamic link to the original 
segment y because the reference name y is still associated with the original 
segment and segment number. The system maintains this association until the 
reference is terminated. See Figure 3-1 for an illustration of initiated segments 
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working_dir_1 


program 


program 


x call y 


working_dir_2 


program program 


y 


z calls y 


Figure 3-1. Initiated Segments 
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Segments can be made known to your process by using the initiate (in) 
command. You can list your initiated segments with the list _ref_names (irn) 
command. References can be terminated by using one of the terminate commands, 
either terminate (tm), terminate refname (tmr), terminate_segno (tms) or 
terminate single refname (tmsr), which allow you to remove segments from the 
list of segments known to your process. (The new_proe command also erases all 
previous association between segment names and segment numbers, by sweeping out 
your entire address space.) For more detailed information on these commands, 
see the MPM Commands. 


Deleting a segment also terminates it. Recompiling a program unsnaps all 
links in the current process which point to the program, since the location of 
symbolic entry points may be changed by recompilation. Both of these actions 
affect only the process performing the operation. Recompiling or deleting a 
segment in one process may cause other processes uSing the segment to malfunction. 


USES OF DYNAMIC LINKING 


There are many ways in which dynamic linking can be used, but the following 
three are probably the most significant: 


e to permit initial debugging of collections of programs before the entire 
collection is completely coded. 


e to permit a program to include a conditional call to an elaborate 
error handling or other special-case handling program, without invoking 
a search for or mapping of that program unless the condition arises in 
which it is actually needed. 


e to permit a group of programmers to work on a collection of related 
programs, such that each one obtains the latest copy of each subroutine 
as soon as it becomes available. 


The use of dynamic linking in program development is shown by the following 
script. When the script starts, the program "k" and subprogram "y" have already 
been written and compiled by our user MacSissle. 


k: procedure; 


declare (x, y, Z) entry; 
declare i fixed binary; 
declare (sysprint, sysin) file; 


put. ist. ("Which option?™); 
get list (i); 
If 3:.-5° ) then call x3 
else if i = 2 then call y;3 
else if i = 3 then call Z3 
else put list ("Bad option 
return: 

end k; 


y: procedure; 
declare sysprint file; 
put list ("y has been called."); 
put skip; 
end y3 


In this example and all others like it in this manual, comments on the 
script are distributed throughout the script itself. 
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Which option? ! 2 


y has been called. 


ro oUfs7). 05-123. 


The program "k" is invoked by typing its name. MacSissle calls for option 
2, and the program "y" is called. "kK" runs successfully even though two of the 
three subroutines it could call do not exist, because the subroutine it does 
call is available. Since linking is done on demand, and no demand for "x" or 
"2" occurs, their nonexistence does not keep the program from running. 


In the next use of "k", MacSissle asks for an option corresponding to the 
program "z," which doesn't exist. 


tok 
Which option? ! 3 
Error: Linkage error by >udd>ProjA>MacSissle>ki152 (line 11) 
referencing z1z 
Segment not found. 
r 17:11 0.283 90 level 2 


The attempt to call the nonexistent subroutine "z" fails. The linkage 
error handler invokes a second command level, as indicated by the field "Level 
?" an the ready message. The error message shows the full pathname of the 
program attempting to locate "z," and gives the name of the program that could 
not be found. The notation "ziz" means entry point "z" in segment "z." It is 
necessary to separate entry point name from segment name, since a PL/I program 
in a segment could have several entry points with different names. 


Execution of "k" is suspended, since it cannot continue with the call. 
MacSissle has the choice of giving up, or creating "2." She invokes the qedx 
editor and creates the segment. 


qedx 
a 
Zz: procedure; 
declare sysprint file; 
list: A"This: is 2") 
skip; 


q 
r 17:12 0.382 48 level 2 


Now the segment must be compiled to create a callable object segment. 


pli z -table 
PL/I 


r 17:12 0.234 65 level 2 


With the object segment "z" created, the call from "k" can be restarted. 
MacSissle does this with the start command. 
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start 


This 28S 
PTS 12. O66 27 


The program finishes successfully. It can now be run with option 3 without 
any additional intervention. 


kK 
Which option? ! 3 
THis: 28:52 


re T72-13:05 07S: 16 


For more information on the details of dynamic linking, see the MPM Reference 
Guide sections on object segments, system libraries and search rules. You might 
also want to learn about the resolve_linkage_ error (rle) command, which can be 
used to satisfy the linkage fault after your process encounters a ‘Mainkape error. 
This command is described in the MPM Commands. 


SEARCH PATHS 


.Searching is something that Multics has to do all the time. So far we've 
only talked about searching for object segments--what Multics has to do when you 
type the name of a program you want to execute, or your program references an 
external procedure. Multics has to search for other things, too, notably input 
of some kind. For example, the help command requires as input an info segment. 
You can tell the system to look in specific places for the input by creating 
search paths. Search paths have the same basic function as search rules, but 
are used for things like subsystems and language compilers. A set of commands 
similar to those available for modifying search rules are available for modifying 
search paths. These commands are add search paths (asp), delete _search_paths 
(dsp), print_search_paths (psp), set search paths (ssp), and where search paths 
(wsp). All are documented in the MPM Commands. 
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SECTION 4 


INPUT/OUTPUT PROCESSING 


Input/output (I/0) processing on Multics can be handled in many different 
ways. The intent of this section is to show you how to do simple kinds of I/0 
on Multics, and to introduce you to the basics of doing more complex I/O. 


The Multics I/O system handles logical rather than hardware I/O. This 
means that I/0 on Multies is essentially device independent. In other words, 
you don't have to write your program with a specific device in mind. Most I/0 
operations refer only to logical properties (e.g., the next record, the number 
of characters in a line) rather than to particular device characteristics or 
file formats. To understand how I/O processing on Multics works, you must first 
be familiar with two important terms. 


(1) I/O switeh: a software construct through which the file name in your program 
is associated with an actual device. The I/O switch is like a channel, in 
that it controls the flow of data between your program and a device. It 
keeps track of the association between itself and the device and the I/0 
module. 


(2) I/C module: a system or uSer-written program that controls a physical device 
and acts as an intermediary between it and your program. The I/O module 
knows what the attributes of the device are, and "hides" them from you so 
you don't have to worry about them. It processes the I/0 requests that are 
directed to the switch attached to it. The Multics system offers the following 
I/O modules: 


discard _ 
provides a "sink" for unwanted output. 


rdisk 
supports I/O directly from/to removable disk packs. (These are packs 
which are allocated in their entirety to a process; they do not contain 
files in the Multics storage system.) 


record _stream_ 
provides a means of doing record I/O on a stream file or vice-versa. 


syn 
establishes one switch as a synonym of another. 


tape_ansi 


supports I/O from/to magnetic tapes according to standards proposed by 
the American National Standards Institute (ANSI). 
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tape_ibm_ 
supports I/O from/to magnetic tapes according to IPM standards. 


tape_mult_ 
supports I/0 from/to magnetic tapes in Multics standard tape format. 


tape_nstd_ 
supports I/0 from/to magnetic tapes in nonstandard or unknown format. 


tty 
Supports I/O from/to terminals. 


vfile 
supports I/0 from/to files in the storage system. 


Figure 4-1 illustr 
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THE FIVE. BASIC SIEPS OF INPUT /OUTPUT 


re 


For every input/output data stream you are using, you must follow the 5 
basic steps of Multics I/O processing, which involve attaching an I/0 switch to 
an I/O module, opening the switch, performing the data transfer, closing the 
switch, and detaching it from the I/O module. These steps may be accomplished 
outside of your program by means of commands input before and after your program 
runs, or inside your program by means of subroutine calls or language I/0 statements. 
(Defaults are arranged so you can often appear to skip these steps, and they 
will be done correctly anyway.) 


(1) Attach the Switch 
This step associates your data with a file in your program. The switch is 
the program's name for each data stream. (In FORTRAN, switches are called 
file05, filei1C, etc.) An attachment statement in Multics is comparable to 
a JCL data definition (DD) statement in IBM systems. A switch remains 
attached until you detach it or you issue a new_proc or logout command. 


A switch may be attached by: 


® invoking the io_call command 


e issuing a call to the iox_ subroutine 


e using a language open statement (if the switch hasn't been previously 
attached) 
e using the default attachments associated with PL/I gets and puts, 


FORTRAN reads and writes, or COBOL reads and writes 
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Figure 4-1. Flow of Data 
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(2) 


Cpen the Switch 


This step describes the data you're going to use. It tells the system how 
the data is organized (its file type) and how it is to be accessed (its 
mode). Data sets can be organized in four fundamental ways: stream, 
sequential, blocked, and keyed. Only the first two ways will be discussed 
here. 


A stream file is a collection of data that is like free-form text. The 
data is a continuous flow of information, with individual items separated 
by blanks, commas, or newline characters. A stream file can be created, 
examined, and updated via a text editor, and can be meaningfully printed on 
a terminal or line printer, because it contains only ASCII characters. 
It's size is arbitrary. 


A sequential file is a collection of data that is broken into discrete 
units called records, which have a fixed form. A sequential file is created 
by a program, and is used for information which is meant to be read and 
processed by another program. The data are in the same coded form as data 
stored internally in the computer and can't be printed meaningfully. 


Most tape files are sequential. Disk files may be either stream or sequential. 
Terminal I/O is stream-oriented. 


Data sets can be operated on in three fundamental ways: input only, output 
only, or both input and output. Some of the opening modes of a switch are 
therefore: 


si - stream input sqi - seouential input 
so - stream output sqo - sequential output 
sio - stream input/output sqio - sequential input/output 


A switch may be opened by: 

e invoking the io call command 

e issuing a call to the iox_ subroutine 
® uSing a language open statement 


e using PL/I gets, puts, reads, and writes, FORTRAN reads and writes, or 
COBOL reads and writes--the switch is opened by default 


(3) Perform I/O Operations 


This step is where the data transfer actually cccurs. 


Data transfer may be performed by: 


@ invoking the io_call command 
e issuing a call to the iox_ subroutine 


e using language defined I/O statements (gets, puts, reads, writes, etc.) 


(4) Close the Switch 


This step tells the system you are through (at least temporarily) with the 
I/O switch. It prevents further access to the data through that switch, 
enables you to re-open the switch later with a different mode, and with 
output disk files and tapes, sets the length of the file. 
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A switch may be closed by: 

s invoking the io call command 

* issuing a call to the iox_ subroutine 
& using a language close statement 


e default (on your program's return), if and only if the switch 
was opened by default 


(5) Detach the Switch 


This step disconnects your program from your data. 


A switch may be detached by: 


2 invoking the io_call command 
ad issuing a call to the iox_ subroutine 
& using a language close statement 


es default (on your program's return), if and only if the switch 
was attached by default 


The simplest way to do I/0 on Multics is to use the terminal. There are 


four standard switches which are attached when your process is created. 


(1) 


(2) 


(3) 


(4) 


user i/o: this switch acts as a common collecting point for all terminal 
I/O. It's attached to your terminal through the I/O module tty_ and opened 
for stream input and output. 


user_input: this switch controls command and data input at the terminal. 
It's attached to user_i/o through the I/O module syn_, and through that to 
your terminal. It's opened for stream input. 


user_output: this switch controls command and data output at the terminal. 
It's attached to user_i/o through the I/O module syn_, and through that to 
your terminal. It's opened for stream output. 


error output: this switch controls output of error messages at the terminal. 
It's attached to user_i/o through the I/O module syn_, and through that to 
your terminal. It's opened for stream output. 


Figure 4-2 illustrates these standard attachments. 
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Figure 4-2. Standard Attachments 
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If you don't specify switch names and I/O modules when you run your program, 
the system uses these defaults. So, it's possible to write your program using 
the terminal for input and output and not worry about files. For example, here 
is a revised version of our sample program from Section 2, simple sum. It has 
been renamed any_sum, and changed to accept input typed by the user at the 
terminal in response to a prompting message. The output is typed back on the 
terminal. Notice the use of sysin and sysprint for the terminal input and 
output. 


any sum: proce options (main); 


/* this program computes the sum of any three 1 to 6 digit numbers typed 
at the terminal, then prints the answer at the terminal ¥*/ 


declare 
sysin file, the terminal input */ 
sysprint file, the terminal output ¥*/ 
first_no fixed binary (20), the first number */ 
second no fixed binary (20), the second number */ 
third no fixed binary (20), the third number */ 
the sum fixed binary (24); the answer */ 


the three numbers */ 


put skip list ("please type three 1 to 6 digit numbers:"); 
get list (first no, seeond_no, third_no); 


them up */ 
the sum = first_no + second_no + third_no; 
/*® print the answer */ 


put skip list ("the sum of the three numbers is:", the_sum); 
put skip; 


end any_sum; 


Here are FORTRAN and COBCL versions of the same program. 


This program computes the sum of any three numbers typed at the 
terminal, then prints the answer at the terminal. 


integer first no, second_no, third_no ! the 3 numbers 
integer the_sum ! the answer 


Get the three numbers 


print, "please type three numbers:" 
input, first_no, second_no, third_no 


Add them up 
the _sum = first_no + second_no + third_no 


Print the answer 


print, "the sum of the three numbers is:", the_sum 


stop 
end 
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Detailed information about how the command utility and active function error 
subroutines can be used from an active function procedure is provided in the MPM 
Subroutines and the MPM Subsystem Writers' Guide respectively. 


The same procedure can be programmed to operate both as an active function 
and as a command procedure. Typically when such procedures are called as a 
command, they print on the user's terminal the value of the string they would 
return as an active function. These command/active function procedures are coded 
as active functions and should call cu $af return arg instead of cu $af arg count. 
If cu $af_return_arg returns the error codé error table $not_act_fne, they operate 
as commands. If the code returned is zero, they use the returned pointer and 
length to base the return value. Any other nonzero error code should be fatal. 
Note that cu_$af_return_arg always returns a correct argument count even if the 
active function was invoked as a command, so the user can go on to use cu_$arg ptr 
with no further checking. 


ADDRESS SPACE MANAGEMENT 


When a user logs in, he or she is assigned a newly created process. Associated 
with the process is a collection of segments that can be referenced directly by 
system hardware. This collection of segments, called the address space, expands 
and contracts during process execution, depending on which segments are used by 
the running programs. 


Address space management consists of constructing and maintaining a 
correspondence between segments and segment numbers, segment numbers being the 
means by which the system hardware references segments. Segment numbers are 
assigned on a per-process basis (i.e., for the life of the process), by supplying 
the pathname of the segment to the supervisor. This assignment is referred to 
as "making a segment known." Segments are made known automatically by the dynamic 
linker when a program makes an external reference; making a segment known can 
also be accomplished by explicit calls to address management subroutines. In 
addition, when a segment is made known, a correspondence can be established 
between the segment and one or more reference names (used by the dynamic linker 
to resolve external references); this is referred to as "initiating a reference 
name." When dynamic linking is the means used to make a segment known, the 
initiation of at least one reference name is performed automatically. (For more 
information on reference names, see "Reference Names" in Section 3 and "Making a 
Segment Known" below.) A general overview of dynamic linking is given below. 


Dynamic Linking 


The primary responsibility of the dynamic linker is to transform a symbolic 
reference to a procedure or data into an actual address in some procedure or 
data segment. In general, this transformation involves the searching of selected 
directories in the Multics storage system and the use of other system resources 
to make the appropriate segment known. The search for a referenced segment is 
undertaken after program execution has begun and is generally required only the 


- ° = tun aaAA oo 
first time a program references the address. 


The dynamic linker is activated by traps originally set by the translator in 
the linkage section of the object segment. These traps are used by instructions 
making external references. When such an instruction is encountered during 
execution, a fault (trap) occurs and the dynamic linker is invoked. 
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The dynamic linker uses information contained in the object segment's 
definition and linkage sections to find the symbolic reference name. (For a 
detailed description of these sections, see "Multics Standard Object Segment" in 
Section 1 in the MPM Subsystem Writers’ Guide.) Using the search rules 
currently in effect, the dynamic linker determines the pathname of the segment 
being referenced and makes that segment known. The linkage trap is modified so 
that the fault does not occur on subsequent references; this is referred to as 
snapping the link. 
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identification division. 
program-id. anysum. 
author. KMacSissle. 
date-written. February 1981. 
date-compiled. 
remarks. This program computes the sum of any three 1 to 6 digit 


numbers typed at the terminal, then prints the answer at the 
terminal. 


environment division. 
configuration section. 
source-computer. Multics. 
object-computer. Multics. 


data division. 
working-storage section. 


01 first-no pic 9(6) value zeroes. 
C1 second-no pic 9(6) value zeroes. 
01 third-no pie 9(6) value zeroes. 
01 the-sum pic 9(7) value zeroes. 


procedure division. 


100-get-three-numbers. 
display "please type three 1 to 6 digit numbers". 
display "(numbers less than 6 digits long must be zero-filled,". 
display " and each number must be typed on a new line):". 


accept first-no. 
accept second-no. 
accept third-no. 


200-add-them-up. 
compute the-sum = first-no + second-no + third-no. 


300-print-the-answer. 
display "the sum of the three numbers is: ", the-sunm. 
stop run. 


USING SEGMENTS AS STORAGE FILES 


ee 


When your application requires the use of a storage file for I/0, the 
easiest thing to do is to use a segment in your working directory (or a segment 
in another directory to which you have created a link). In your program, you 
must do the following: 


(1) Give the file a name and declare it as a file; 


(2) Open it (connect it to your program, prepare it for processing, and position 
it at the beginning); 


(3) Do data transfer via one or more get, put, read or write statements (depending 
on the language you're using); 


(4) Close it (disconnect it from your program). 
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Here is a revised version of the any sum program. It's been renamed compute sum, 
and changed so that it gets its input from a segment in your working directory 
called in_file. The output goes to another segment in your working directory 
called out_file. 


compute sum: proc options (main); 


/* this program computes the sum of three 1 to 6 digit numbers read from 
an input file, then writes the answer to an output file */ 


declare 
in_file stream file, /* the input file ¥*/ 
out_file stream file, /* the output file */ 
first_no fixed binary (20), /* the first number */ 
second no fixed binary (20), /* the second number */ 
third no fixed binary (20), /®* the third number */ 
the_sum fixed binary (24); /* the answer */ 


open the files */ 


open file (in file) input, 
file (out_file) output; 


get the three numbers from the input file */ 

get file (in_file) list (first_no, second_no, third_no); 
add them up */ 

the_sum = first_no + second_no + third_no; 
put the answer in the output file ¥/ 


put file (out_file) list (the_sum); 


close the files */ 


close file (in file), 
file (out file); 


end compute _sum; 


Doing I/O this way also takes advantage of the default switches and modules. 
The open statement attaches and opens the switch, the close statement closes and 
detaches the switch. 


What if the files you need to use are not segments in your working directory? 
One thing you can do, if you're a PL/I programmer, is to use the title option on 
your open statement. For example: 


open file (in_file) title 
("vfile_ >udd>ProjA>MacSissle>data_files>test_file_1") input; 


where 

vfile_ >udd>ProjA>MacSissle>data_files>test_file 1 
is an example of an attach description. An attach description is a string of 
characters which identify the name of an I/O module and options to control its 


operation. In this case, the only option given is the source/target of the 
attachment (i.e., the name of the device or file). 
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Other languages have constructs which are somewhat similar to the PL/I 
title option. In FORTRAN, there is the attach specifier, which is used on an 
open statement. In COBCL, there is the catalog-name clause. See the Language 
Users' Guides for information on how to use these constructs. 


USING I/O COMMANDS AND SUBROUTINES 


ee 


The use of I/O commands and subroutines is where I/O processing may become 
more complex. The following discussion is not intended to fully explain their 
use, but rather, to introduce the basic concepts involved. For more information, 
refer to the MPM Reference Guide, Section 5. Information is also available in 
the Language Users' Guides. 


The command for performing operations on designated I/0 switches is io_call 
(io). Its syntax is: 


io opname switchname {args} 


It is used as follows: 
(1) To attach a switch: 


syntax: io attach switchname modulename {args} 
example: io attach my switch vfile_ >udd>ProjA>MacSissle>my_file 
f >ud 


(vfile udd>ProjA>MacSissle>my_ file is another example of an attach 
description. 


ww OL 


(2) To open a switch: 


syntax: io open switchname mode 
example: io open my switch sequential_input 


(3) To close a switch: 


syntax: io close switchname example: io close my_switch 


(4) To detach a switch: 


syntax: io detach switchname example: io detach my_switch 


The io_call command is used outside of your program. A typical sequence at 
command level would involve attaching and opening the switches, running your 
program, then closing and detaching the switches. (Switches that are attached 
and opened at command level should usually be closed and detached at command 
level. However, they can also be closed explicitly by the program using language 
close statements.) 


Other I/O-related commands include: 


close file (cf) 
closes specified FORTRAN and PL/I files. This command is very useful if 
your program opens a file, tnen terminates unexpectedly before closing 
it. You must close the file before you run the program again, or you'll 
get an end-of-file error. 
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ecopy_cards (ced) 
eopies specified card image segments from the system pool storage 


into 


your directory. The segments to be copied must have been created using 


the Multics card image facility. 


copy file (epf) 
eopies records or lines from an input file to an output file. 


display_pllio_error (dpe) 


describes the most recent file on which a PL/I I/0 error was raised and 


displays diagnostic information associated with that error. 


file output (fo) 


directs all subsequent output over user output to a specified segment. 


print_attach_table (pat) 
prints information about I/O switch attachments. 


revert_output (ro) 
restores all subsequent output to the previous device. 


stop_cobol_run (ser) 
causes the termination of the current COBOL run unit. 


terminal_output (to) 
directs all subsequent output over user output to a terminal. 


Three of these commands can show you a little about how switches work. 
"pat" on your terminal and the system will print this: 


user i/o tty_ -login_channel 
stream input_output 


user_input syn_ user_i/o 
user output syn_ user_i/o 
error output syn_ user_i/o 


Type 


You can see from this that user_i/o is attached via the module tty_ to the login 
channel, and user_input, user_output, and error output are attached via the module 


syn_ to user_i/o. 


Type "fo my_file; pat; ro; pr my file" on your terminal and the system will 


print something like this: 


my file 03/10/81 1124.0 est Mon 


user_i/o tty_ -login_channel 
stream _input_output 
user_input syn user i/o 


user_output syn_ fo_!BBBJKqdcZHXHFf 
error _output syn_ user_i/o ; 
fo_save_!BBBJKqdcZJXgxW | 
syn_ user_i/o 
fo_!BBBJKqdcZHXHFf vfile_ >udd>ProjA>MacSissle>my file -extend 
stream output 


You can see from this that user output was attached via vfile_ instead of syn_. 


(Refer to Figure 4-3.) For complete information on all of these commands, 
the MPM Commands. 


see 
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The most important subroutine for doing I/0 is iox. It is called from 
within your program just like any other subroutine, and can be used to attach, 
open, close and detach switches, as well as to read and write records, and 
perform various other I/O cperations. Another subroutine for doing I/0 is ioa , 
which is used for producing formatted output; it can be very handy. The use of 
these subroutines is beyond the scope of this manual. Detailed information is 
available in the MPM Subroutines. 


CARD INPUT AND CONVERSION 


You may have programs punched on cards that you would like to compile and 
run under Multics. The standard way of handling a card deck on Multics is to 
place the deck in a card reader and read it into a system pool. Once this is 
done, you log in on a terminal, and transfer the card file from the system pool 
to your working directory using the copy_cards command already mentioned. 


A minimum of three control cards must accompany your deck. These control 
ecards identify you to the system, and specify the format of the card input you 
are submitting. There are two kinds of card input on Multics. One is bulk data 
input, which is usually a program or a data file. The format of a card deck for 
bulk data input is shown below: 


++DATA DECK NAME PERSON ID PROJECT ID 
++PASSWORD PASSWORD = - 
+4+CONTROL OVERWRITE 

++AIM ACCESS CLASS OF DATA CARDS 
++FORMAT PUNCH FORMAT MODES 

++INPUT 


(user data cards) 


The three cards required as a minimum are the first, which is an identifier 
ecard, the second, which is a password card, and the last, which signals the end 
of control input. 


The other kind of card input is remote job entry, which is a series of 
Multics commands to be run as an absentee job. For information on absentee 
jobs, and the format of a card deck for remote job entry, see Section 7. Fora 
complete explanation of all the Multics control cards, see Appendix C of the MPM 
Reference Guide. 
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Figure 4-3. Attachments After Execution of file_output Command 
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SECTICN 5 


A DEBUGGING TOOL 


A variety of debugging tools are available on Multics. They allow you to 
look at your program piece by piece, in a way that is closer to the way the 
machine sees it. The most powerful of these tools is an interactive program 
named probe, which permits source-language breakpoint debugging of PL/I, FORTRAN, 
and COBOL programs. To understand the discussion of probe given later in this 
section, you must first know a little about the Multics stack. 


THE STACK 


Each process has associated with it a stack segment (called the stack) that 
contains a history of the environment. The stack is essentially a push down 
list which contains the return points from a series of outstanding interprocedure 
calls. It also holds storage for automatic variables. If you were to stop a 
running process and trace its stack, you would find, starting at the oldest 
entry in the stack, a record of the procedures used to initialize the process, 
followed by the command language processor, followed by the procedure most recently 
called at command level and any procedures it has called. Your stack can be 
visualized as follows: 


op. 
| eed 
= Fe 


ustration above define stack frames. As control passes 
within the system, your stack "grows" new stack frames: 
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Figure 5-1. State of Stack 


(a) State of Stack after Login 
(b) State of Stack after Command is invoked 
(c) State of Stack after QUIT 
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Figure 5-1le depicts the stack after a QUIT is signalled. Here a second 
command level is established. The first command level, and the program itself, 
have been suspended, but nothing has been thrown out. 


At this point further commands could be issued. The start command would 
cause the program to resume execution, and the stack to revert to the state 
illustrated in Figure 5-1b. The release command would cause the stack frame 
(and hence the execution state) of the program to be discarded, and the stack to 
revert to the state depicted in 5-la. 


Note that it would be possible at the second command level (Figure 5-1e) to 
invoke the same program called at the first command level. 


Figure 5-2 illustrates several of the states of the stack during execution 
of a program consisting of several subprograms. The call/return sequence depicted 
I 


Program A calls program B 

Program EB calls program C 

Program C returns to B 

Program B calls program D 

Program D returns to E 

Program B returns to A 

Program A returns to command processor 


These diagrams illustrate the behavior of four separately compiled programs, 
each allocated a new stack frame every time it is called: 
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(a) User at command level. 

(b) A is invoked and gets stack frame, in which automatic variables are 
allocated and initialized. 

(c) A calls B. B gets stack frame, in which automatic variables are allocated 
and initialized. 

(d) Bealls Cc, C gets stack frame, in which automatic variables are allocated 
and initialized. : 

(e) C returns to 8, the stack frame for C is discarded, and storage is 
released. 

(f) Bealls D, D gets stack frame, in which automatic variables are allocated 
and initialized. 

(g) D returns to B, the stack frame for D is discarded, and storage is 
released. 

(nm) B returns to A, the stack frame for B is discarded, and storage is 
released. 

(i) A returns to command level. All program-specific automatic storage 
has been released. 


Automatic storage is storage which stays around only for the life of a 
program. Static storage is storage which stays around for the life of a process, 
or is retained across processes. 


If an unexpected error occurs (or you press the QUIT button), the system 
will save the current environment, mark the stack at its current level, and push 
a frame onto the stack for a new activation of the command processor. 


The new activetion of the command processor accepts commands just as the 
original one did. It is possible to restart the suspended program, or to discard 
the saved environment, or to use one of the Multics debugging tools to examine 
the saved environment. 


The release command causes the command processor to return to its own previous 
activation, and discard the intervening stack contents. The programs whose stack 
contents have been discarded cannot be resumed or examined after the stack has 
been released. 


The start command causes the command processor to attempt to continue execution 
of the suspended program at the point of interruption. Depending on the nature 
of the error, and what has been done since the error occurred, the restart 
attempt may or may not succeed. Programs may always be restarted after a QUIT, 
but only seldom after an error. If the program cannot be restarted, the error 
message will usually be repeated. An unsuccessful attempt to restart a program 
is usually harmless. 


If you would like to examine the stack history of your process in detail, 
try using the trace stack (ts) command, described in the MPM Commands. 


PROBE 


The probe (pb) command can be used to examine the saved stack and the 
current state of suspended programs. (Remember that a program which makes a 
call to another program is suspended just as a program which makes an error is 
suspended, except that a program which makes a call can always be resumed.) 
Probe can print the values of program variables and arguments, as well as reporting 
the last program location to be executed. 


The use of probe is shown here in a series of examples, which make use of 
the following program, blowup.pl1. This program has an illegal reference to the 
array "a", and the subscriptrange condition occurs when it is run. Since 
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subscriptrange checking is disabled by default in PL/I, the error manifests 
itself as an out_of_bounds condition instead of a subscriptrange. (In practice, 
it is recommended that PL/I programmers' enable such conditions as subscriptrange.) 
Although this error is easy to spot, the behavior of the program is typical of 
other, harder to spot errors. 


! print blowup.plt 


blowup.pli 04/17/80 1332.0 mst Thu 


procedure; 


fixed binary; 
fixed binary; 
fixed binary; 


= -1 to -100000 by -1; 
sum =a (j)3 
end; 
end blowup; 


r 13:32 0.110 20 


' plil blowup -table 
PLSL 
PoI3932 O26TS 374 


The program is compiled with the -table control argument. This action 
causes a symbol table to be created, and stored with the program in the executable 
object segment. The information it contains can be used by the Multics debugging 
aids. A symbol table should always be created while debugging, so that errors 
may be found more easily. 


blowup 


Error: out_of_bounds at >udd>ProjA>MacSissle>blowup;24 (line 9) 


referencing stack _4{777777 (in process dir) 
Attempt to access beyond end of segment. 
r 13:32 0.228 32 level 2 


The program is invoked by typing its name. It takes an ‘out_of_bounds' 
fault, because the subscript used in the reference to array "a" is invalid. The 
program does not use PL/I subscriptrange checking, so it attempts to calculate 
the address of ‘the (nonexistent) element of "a" referenced. The resulting address 
does not exist, so the fault occurs. 


This message shows the name of the error condition, the pathname of the 
program, the octal location in the object segment where the error occurred, the 
line number, and an additional message about the error. If blowup was a FORTRAN 
program, the pathname would look like this: >udd>ProjA>MacSissle>blowup$main , 
blowup being the name of the segment and main_ the name of the program entry 
point. This is because every FORTRAN program has a "main" program entry point 
and Multics uses this as part of its name. If the program had not included a 
symbol table, the line number would not have been part of the message. 


! probe 


Condition out_of_bounds raised at line 9 of blowup (level 7). 
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MacSissle invokes the probe command. Probe looks: for the program which 
caused the trouble, and prints a message about the most recent error found in 
MacSissle's process. The word "level" here refers not to command processor 
level, but to the number of programs saved on the stack. The error occurred in 
blowup, which was the seventh program on the stack. 


Yn 
ct 
~~ 
Q 
“< 


read list!13400 
command_processor_| 10301 
abbrev_17507 

release stack{}7355 
unclaimed signali24512 
walli4410- 


=— MW FUNAAT WO DO AH NW 


blowup (line 9) out_of_bounds 
read_list{ 13400 

command processor_110301 

abbrev 17507 
Listen: (7355 
process overseer 
user_init_admin 


135503 
TH0100 


The stack is displayed by the "stack" request. This request shows every 
program on the stack, in the order invoked. There will always be unfamiliar 
programs on your stack. You can just ignore them--they are for handling errors, 
processing command, ete. The numbers on the left show the order of activation. 
The entry for blowup shows the source line number corresponding to the last 
location executed, and the name of the error that occurred. The line number can 
be determined because blowup was compiled with a symbol table. The other programs 
have no symbol table, so the display shows the cctal offset of the last instruction 
executed. 


! source 
sum = a (j)3 


Using the "source" request, the source statement for line 9 is displayed. 
This is the line that was being executed when the error occurred. More precisely, 
the error occurred executing the object code corresponding to this source line. 


value j 

j = -2689 

symbol a 

fixed bin (17) automatic dimension (10) 
Declared in blowup 


The value of the variable "j" is displayed with the "value" request. This 
request takes as its argument the name of a variable, and prints the value of 
the variable. (Note that a program must be suspended for you to look at its 
automatic variables.) Next, the "symbol" request is used, to show the attributes 
of Wa lf" 


! position 8 


do j = -1 to -100000 by -1; 
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The "position" request is used to examine different lines of the program, 
in this case the line before the one that caused the hang. This request can 
also be used to examine different programs cn the stack. For example, to look 
at the abbrev program on level 4, MacSissle could type “position level 4". 
However, she would most likely get the answer "probe (position): Cannot get 
statement map for this procedure," which means that the program was not compiled 
with the -table option. (Most system commands have -table omitted, to save 
space.) 


! “Gu Et 


r 13:33 1.080 129 level 2 


The last probe request used is "quit," which exits probe, and returns to 
command jlevei. MacSissie is still at command level two, and the program is 
still intact. The next command typed is the release command, which discards the 
saved frames, returning to level one. 


! release 


py o13233-0..057 16 


Unlike interactive programs like read_mail, probe doesn't prompt you for 
requests. If you're not sure whether probe is listening, type a dot, and probe 
will respond with "probe 5.2" (or whatever the version number is) if it is 
there. 


Probe has many more features than there is room to present here. It should 
still be useful to you even if you don't use the other features, but to learn 
about them you can use the "list requests" request, which tells you the name of 
every probe request, and the "help" request, which tells you about probe requests 
and also about probe itself. For example, you can type “help value" to find out 
about the "value" request, or "help help" to find out about "help". 


Another debugging tool which you may find useful is the trace command, 
which allows you to monitor all calls to a specified set of external procedures. 
Full descriptions of the probe and trace commands are available in the MPM 
Commands. 
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SECTION 6 


A PERFORMANCE MEASUREMENT TOOL 


After a program is written and debugged, it is often desirable to increase 
its efficiency. Multics provides performance measurement tools which identify 
the most expensive and most frequently executed programs in a given collection. 
Within these crucial programs, the most costly lines are found by using the 
profile facility. 


To use the profile facility, the first thing you have to do is compile your 
program with the -profile control argument. This control argument causes the 
compiler to generate special code for each statement, recording the cost of 
execution on a statement-by-statement basis. Then, after executing your program 
many times, you can use the profile command to look at its performance statistics. 


The example that follows shows the use of profile with a very small sample 
program to be used as a subroutine: 


prime : procedure (trial_prime) returns (bit (1) aligned); 
declare trial prime fixed binary (35) parameter; 
declare trial factor fixed binary, 
last_factor fixed binary; 
declare (mod, sqrt) builtin; 
last factor = sqrt (trial prime); 


do trial factor = 2 to last_factor; 
if mod (trial_prime, trial factor) = 
then return ("0"b); 
end; 
return ("1"b)3 
end prime 3 


This subroutine cannot be called directly from command level, since only 
programs whose arguments are nonvarying character strings may be called directly. 
It is to be used with other programs. To test it, a simple command is written 
which accepts one argument, converts it to binary, and calls the prime_ subroutine. 
The testing command is called test_prime. It is not shown here. 


pli prime -profile 
PL/I 
r 17:44 0.699 140 


test_prime 3 
3 is a prime. 
r 17:44 .110 23 
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First, the prime subroutine is compiled using the -profile control argument. 
Next, the test_prime command is invoked with the argument "3". Test_prime converts 
the 3 to binary, and calls the prime_ subroutine with it. 


! discard output "test _prime ([index_set 500])" 


r 17:45 5.103 54 


To evaluate the performance of the subroutine, several hundred calls to it 
should be made, over a wide range of values. The next command line invokes 
test prime 500 times, with values from 1 to 5C0O. The index set active function 
returns the numbers from 1 to 500, and the parentheses invoke test_prime once 
for each value. 


The output from the program is not interesting, so the discard_output (dco) 
command is used. This command causes output from the program to be discarded, 
instead of printed on the terminal. 


l-profile prime. 


Program: prime_ 
LINE STMT COUNT COST STARS OPERATORS 


1000 24000 ¥#RF fx1_to fl2, dsqrt, f12_to fx! 
1000 3000 
4442 13254 #¥x 


4218 59052 XR mod fx1 
800 8800 ** return 
3418 68326 ** 

200 2600 return 


15054 127542 
r 17:46 0.368 51 


While the program was run, performance statistics were saved. Now the 
profile command is used to display those statistics. For each line, it displays 
the total times executed, an estimate of the cost, and the PL/I operators used. 


Note that some statements (those in the loop) were executed more than others. 
The COST for a statement is the product of the number of instructions for the 
statement and the number of times the statement was executed. This cost does 
not take into account the fact that some instructions are faster than others, or 
the time spent waiting for missing pages (page faults). The STARS column gives 
a rough indication of the relative cost of each statement. 


The names of the PL/I operators used are also given. The operator fxi_to_fl2 
is used to convert the fixed point number to float, so that its root may be 
taken. The dsqrt operator takes the square root. Finally, the operator fl2_to_fx!1 
converts the result back to integer. The PL/I mod builtin is implemented by the 
mod fx1 operator. These operators are the most expensive things in the program. 
Occasionally a program can be rewritten to not require expensive operators. 
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! profile prime_ -sort cost -first 5 


Program: prime 
LINE STMT COUNT COST STARS OPERATORS 
4218 59052 *#k#* mod fx1 
1000 S4COO *#¥#R¥ ffxi to fie, as0qrt. -f l2-to-fx1 
une 13254 KER aoe a 
800 8800 ** return 
3418 6826 FX 


15054 127542 
r 17:46 0.205 49 


When profiling large programs, it is usually desirable to look only at the 
most expensive lines, since they are the only ones of interest. The profile 
command can be instructed to sort the lines by cost, and display the five most 
costly lines in order. 


The profile command can also be instructed to produce a source language 
type of listing with performance statistics adjacent to each source line. Figure 
6-1 shows MacSissle using the profile command with the -list control argument to 
produce such a listing for the compute_sum program. Note that when -list is 
usec, the profile command produces a segment with the same name as the program, 
but with a suffix of "pfl". (Note also that MacSissle has again set her ready 
message to read "Karen is here".) 


More detailed records of execution are available if you compile your program 
with the -long profile control argument. When this is done, the program samples 
the Multics clock before every instruction, so the total time per statement is 
available to the profile command. The performance data from a program compiled 
‘with -long profile is displayed with the profile command. For further information, 
see the MPM Commands description of profile. 
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1 compute_sum: oroc eotions (main)? 
2 
3 /* this program computes the sum of three 1 to 6 digit numbers 
& input file, then writes the answer to an outout file */ 
4 
6 deciare 
7 in file stream file, fe 
& out file stream file, /* 
9 first ino fixed binary (70), /* 
19 secondino fixed binary (20), /* 
11 thirdine fixed hinary (20), fe 
12 the_sum fixed binary (24) sr 
13 
‘148 /*® oren the files */ 
18 
16 Oven fijie Cin file) fnout, 
17 file fout file) outouts 
18 
19 /*x qet the three numbers from the inout file */ 
20 
21 aet file (in_file) list Cfirstine, second nor thirduno); 
22 
2% f/x adg them up x/ 
2a 
25 thersum = first_no + second ino + thirdono; 
26 
27 ¢x put the answer in the output file */ 
2A 
29 eut file Coutrfile) list (theisum)? 
30 
31 /* close the files */ 
3? 
33 close file (in file), 
34 file Coutlfile): 
35 
34 eed ceommutecsum? 
37 
Figure 6-1. Use of profile Command With -list Control Argument 
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third number */ 
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SECTION 7 


ABSENTEE FACILITY 


A common programming pattern is to develop a program online, using debugging 
tools and trying a variety of test cases interactively to check on a program's 
correctness. After the program is working, you may wish to doa large "production" 
run. Since the production run may produce a large amount of output or take a 
long time, you may not wish to wait at your terminal for the results. Production 
runs on Multics are best done using absentee jobs, which are somewhat analogous 
to bateh jobs on other systems. 


An absentee job runs in an environment similar to that of an interactive 
user. In other words, an absentee job uses Multics in much the same way that a 
person does. It logs in to your home directory, and runs your start_up.ec, if 
any. This must be kept in mind, both when writing a start_up.ec and when submitting 
an absentee job. If you forget that your absentee job will run your start _up.ec, 
you may discover that it has stolen your messages or tried to read your mail. 
If you assume that your absentee job will log in to the directory from which you 
submitted it, you may discover that it has run the wrong version of your program. 


A big difference between an absentee job and an interactive user is that an 
absentee job is not associated with a terminal. Its input comes from a file, 
and its output goes to a file. (In an absentee process, the I/0 switches are 
attached to the input and output segments, instead of the terminal.) 


An absentee input file, or control file, is a segment with the suffix 
"“absin". At its simplest, it is just a collection of commands to be executed. 
The language used in an absentee job is the same as that used in exec_coms. It 
is a superset of the command language. You must anticipate any responses or 
commands you must give ahead of time, and put all of this data into your control 
file. 


An absentee job is submitted by supplying the name of the absin file to 
the enter _abs request (ear) command. The absin file is not copied. It stays 


absentee job. You must not, for example, edit a file it is using, or recompile 
a program it is running. 


The absentee job is placed in a queue and run as "background" to the normal 
interactive work of the system. This technique allows the system to utilize its 
rescurces most effectively, by keeping a queue of jobs that can always be run, 
and delayed for serving interactive users. For these reasons, the charging rate 
for absentee jobs is normally substantially lower than for interactive work. 


Output from an absentee job goes into a file whose name is the same as the 
absin segment, but with the suffix "absout" instead of “absin". When the job 
completes, you may print this absout segment. Figure 7-1 illustrates the differences 
between interactive usage and absentee usage. 
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Figure 7-1. Interactive vs Absentee Usage 
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Suppose MacSissle has written a FORTRAN program which figures square roots. 
The program resides in her directory of FORTRAN programs, and she would like to 
compile and run it absentee. The first thing she does is create a segment 
called compile run.absin. 


ewd >udd>ProjA>MacSissle>fort_progs 
fortran square root.fortran -list 
dprint -dl square root.list 

square root 

dprint file10 

logout 


Then she types this command line: 
! enter_abs_ request compile run 


Her absentee job is submitted. When it runs, it changes to the proper working 
directory, compiles the program and produces a listing segment, prints the listing 
segment on the line printer and deletes it, runs the program, prints the output 
file "file10" on the line printer, and finally, logs out. 


To run this same absentee job via remote job entry, MacSissle would put the 
statements shown above on cards instead of in a segment. Then she would surround 
her cards with control cards and put the deck in a card reader. Her absentee 
job would be executed automatically. 


The format of a card deck for remote job entry is shown below: 


++RJE DECK NAME PERSON ID PROJECT ID 
++PASSWORD PASSWORD = 

++AIM ACCESS CLASS OF ABSENTEE PROCESS 
++RJECONTROL CONTROL ARGS TO THE EAR COMMAND 
++RJEARGS ARGUMENTS FOR THE ABSENTEE PROCESS 
++EPILOGUE COMMAND 

++FORMAT PUNCH FORMAT MODES 

++INPUT 


(user absentee file) 


The three cards required as a minimum are the first, which is an identifier 
ecard, the second, which is a password card, and the last, which signals the end 
of control input 


For another example, suppose MacSissle wants to use the prime_ subroutine 
discussed in Section 6 to check the prime-ness of the first five integers, and 
she wants to use the absentee facility to do it. Remember that prime_ is called 
by test prime, and that the index_set active function can be used to return a 
set of numbers. 
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qedx 

a 

test prime ([index_set 5]) 
\f 

w test5.absin 


q 
r 16:40 0.218 39 


MacSissle uses the Qedx editor to create her absin file. 


| ! enter abs request test5 -notify | 


ID 210805.1; 5 already requested 
r 16:41 0.450 63 


Multics confirms her submission, giving the request id and the number of 
previously submitted jobs in the absentee queue. Often, many of these jobs may 
be "deferred", which is to say, they will not be run until a later time. Thus, 
"5 already requested" doesn't necessarily mean that five jobs must be run before 
MacSissle's job will run. 


A = mea sah N--A AN Dep FA SMa 
Absentee job >udd>ProjA>Mac 


logged in. 


From Initializer.SysDaemon (absentee) 04/21/80 1641.4 mst Mon: 
cSi 


isslie>test5.absin 210805. i 


MacSissle used the -notify control argument on her ear command, so the 
system sends her a message when her job logs in. 


! who -absentee 


Absentee users 3/9 
JQUser.ProjB* 
TSmith. ProjA*® 
MacSissle.ProjA*® 

r 16:42 0.272 22 


MacSissle uses the who command to print a list of all absentee jovs. It 
shows that there are three already running, and that a total of nine can run at 
one time. Absentee users are identified by the asterisk after their project. 


From Initializer.SysDaemon (absentee) 04/21/80 1643.1 mst Mon: 


Absentee job >udd>ProjA>MacSissle>test5.absin 210805.1 
logged out. 


The system also sends her a message when her job logs out. 
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! print test5.absout 


test5.absout 04/21/80 1643.6 mst Mon 


Absentee user MacSissle ProjA logged in: 04/21/80 1641.4 mst Mon 
r 16:41 2.364 55 


test prime ([index_set 5]) 
is a prime 
is a prime 
is a prime 
is not a prime 
is a prime 
16:42 0.198 20 


abs_io_: Input Stream exhausted. 


Absentee user MacSissle ProjA logged out 04/21/80 1643.1 mst Mon 
CPU usage 3 sec, memory usage 1.0 units 


MacSissle's job is done, so she prints the absout segment. 


With more advanced use of the absentee facility, you can also supply arguments 
to be substituted inside the absentee control segment, make absentee job steps 
conditional, delay absentee work until a chosen time, and develop a periodic 
absentee job which is run, say, once every two days. 


The next example shows how absentee jobs can accept arguments. 


! print prime.absin 
prime.absin 04/21/80 1655.7 mst Mon 
test_prime ([Lindex_set &1]) 


r 16:55 -110 19 


This absin segment accepts one argument. The character string "&1" is 
replaced by the argument wherever it occurs. MacSissle tests it by invoking it 
as an exec com. In order to use the absin segment as an exec com, it must have 
a name with the suffix "ec" added to it. ~ 


! add name prime.absin prime.ec 
r 16:56 0.100 5 


! exec_com prime.ec 2 


test_prime ([Lindex_set 2]) 
1 is a prime 
2 is a prime 


r 17:00 0.210 30 


MacSissle invokes the exec_com with the argument 2. As it runs, it prints 
the commands in the file. The argument mechanism seems to work, so she submits 
an absentee job. 
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! enter abs request prime.absin -arguments 100 


ID: 221023.4; 6 already requested. 
r 17:05. 0.273 50 


Here, the argument 100 is passed to the absentee job. MacSissle goes about 
other business while the request runs. 


A common problem for many users is an absentee job that blows up unexpectedly 
because it is asked an unanticipated question, and the user has not provided an 
appropriate answer. For example, a job may be asked, "Do you wish to quit?" It 
can try to use its next command for an answer, but it will be told to "Please 
answer yes or no." At this point, the job will probably die. 


Suppose MacSissle has set up a daily absentee job that reads her mail. Her 
absin segment, called mail.absin, looks like this: 


enter _abs request mail -time "07:00" -notify 
read mail 


print all 
quit 
dprint -delete mail.absout 


MacSissle types the command line 
! enter_abs request mail -time "07:00" ~-notify 


once. Her absentee job submits a request for the next absentee job, then reads 
her mail. Once in the read_mail request loop, it asks that all of her mail be 
printed, then quits out of the loop. Finally, it dprints her absout segment. 


This job seems like it should work fine. But what will happen if MacSissle 
doesn't have any mail? The request to read her mail will return the answer, 
"You have no mail". Then the request to print all of her mail will return the 
answer, "Segment all not found". The request to quit will return a similar 
answer. So, the job may not die in this case, but it will give MacSissle some 
unexpected results. To avoid this problem, MacSissle can change her absin segment 
to look like this: 


enter_abs request mail -time "07:00" -notify 


read_mail -request "print all; quit" 
dprint -delete mail.absout 


Now, if she has no mail, she'll just get the answer, "You have no mail", 
which is what she wants. 


For further information on absentee jobs, see the MPM Commands manual 
descriptions of the enter_abs request and exec _com commands. See also the 
descriptions of the pli_abs, cobol_abs, and fortran_abs commands, which invoke 
language compilers in absentee jobs. 
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SECTION 8 


REFERENCE TO COMMANDS BY FUNCTION 


All of the Multics commands described in the MPM Commands are arranged here 
according to function and are briefly described. The Multics command repertoire 
is divided into the following 17 groups: 


Aecess to the System 

Storage System, Creating and Editing Segments 
Storage System, Segment Manipulation 

Storage System, Directory Manipulation 

Storage System, Access Control 

Storage System, Address Space Control 

Formatted Output Facilities 

Language Translators, Compilers, and Interpreters 
Object Segment Manipulation 

Debugging and Performance Monitoring Facilities 
Input/Output System Control 

Command Level Environment 

Communication Among Users 

Communication with the System 

Accounting 

Control of Absentee Computations 

Miscellaneous Tools 


Many commands can perform more than one function, so they are listed in 
more than one group. 


Detailed descriptions of these commands, arranged alphabetically rather than 
functionally, are given in the MPM Commands. In addition, many of the commands 
have online descriptions, which you may obtain by invoking the help command. 


ACCESS TO THE SYSTEM 


dial connects an additional terminal to an existing 
process 

echo sets terminal into echoplex mode before login 

enter eonnects an anonymous’ user to the system 

enterp (used at dialup only) 

hangup terminates communication between vermont and 
Multiecs 

hello repeats greeting message printed when terminal 
is first connected 

login connects registered user to the system (used 
at dialup only) 

logout disconnects user from the system 

modes sets terminal modes before login 

slave changes service type of channel from login to 


slave for duration of connection 
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terminal_type 
MAP 


029 and 963 


STORAGE SYSTEM, CREATING AND 


adjust _bit_count 
eanonicalize 
compare_ascii 
compose 

edm 


emacs 


indent 


merge ascii 
qedx 


set bit count 


ted 


sets terminal type before login 

tells system user is attempting to gain access 
from terminal whose keyboard generates only 
uppercase characters 

tells system whether user is attempting to 
gain access from device similar to EBCDIC 


or Correspondence code IBM Model 2741 


EDITING SEGMENTS 


sets bit count of a segment to last nonzero 
word or character 

ensures that contents of a segment are in 
canonical form 

compares ASCII segments, reporting differences 

composes formatted documents for production 
on various devices, including terminals 
and line printers 

allows inexpensive, easy editing of ASCII 
segments 

enters the Emacs text editor, which has a large 
repertoire of requests for editing and 
formatting text and programs 

indents a PL/I source segment to make it more 
readable 

merges two or more related ASCII text segments 

allows sophisticated editing, including macro 
capabilities 

sets the Dit count of a segment to a specified 
value 

used to create and edit ASCII segments; can 
do many kinds of text processing 


STORAGE SYSTEM, SEGMENT MANIPULATION 


adjust_bit count 


archive 
archive table 


compare 


compare_ascii 
copy 


copy_file 
create 

damaged _sw_off 
damaged_sw_on 
delete 


link 


merge ascii 


sets bit count of a segment to last nonzero 
word or character 

packs segments together to save physical storage 

returns the names of specified archive 
components in specified archive segment 

compares segments word by word, reporting 
differences 

compares ASCII segments, reporting differences 

copies a segment or multisegment file and its 
storage system attributes 

copies records from an input file to an output 
file 

creates an empty segment 

resets damaged switch off for segments 

sets damaged switch on for segments 

deletes a segment or multisegment file and 
questions user if it is protected 

creates a storage system link to another 
segment, directory, link, or multisegment 
file 

merges two or more related ASCII text segments 
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move 


set_bit_count 
sort_seg 
tape_archive 
truncate 
unlink 

vfile_ adjust 


volume dump switch off 


volume dump switch_on 


add_name 
eancel retrieval request 
eopy_dir 


create dir 
delete dir 


delete _name 


enter_retrieval_request 
link 


list_retrieval_requests 


list 
move dir 


rename 
safety_sw_off 

safety sw_on 

status 

tape_archive 

unlink 

vfile_ status 

volume _dump_switch_off 


volume dump switch_on 


moves segment or multisegment file and its 
storage system attributes to another 
directory 

sets the bit count of a segment to a specified 
value 

sorts ASCII segments according to ASCII 
collating sequence 

performs a variety of operations to create 
and maintain a set of files on magnetic 
tape 

truneates a segment to a specified length 

removes a storage system link 

adjusts structured and unstructured files 

turns off the specified volume dump switch of 
a segment 

turns on the specified volume dump switch of 
a segment 


STORAGE SYSTEM, DIRECTORY MANIPULATION 


adds a name to a segment, directory, link, or 
multisegment file 

deletes request for a volume retrieval that 
is no longer needed 

copies a directory and its subtree to another 
point in the hierarchy 

creates a directory 

destroys a directory and its contents after 
questioning user 

removes a name from a segment, directory, link, 
or multisegment file 

queues volume retrieval requests for specific 
segments, directories, multisegment files, 
and subtrees 

creates a storage system link to another 
segment, directory, link, or multisegment 
file 

lists retrieval requests in the retrieval daemon 
queues 

prints directory contents 

moves a directory and its subtree to another 
point in the hierarchy 

renames a segment, directory, link, or 
multisegment file 

turns safety switch off for a _ segment, 
directory, or multisegment file 

turns safety switch on for a segment, directory, 
or multisegment file 

prints all the attributes of an entry in a 
directory 

performs a variety of operations to create 
and maintain a set of files on magnetic 
tape 

removes a storage system link 

prints the apparent type and length of storage 
system files 

turns off the specified volume dump switch of 
a segment 

turns on the specified volume dump switch of 
a segment 
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STORAGE SYSTEM, ACCESS CONTROL 


check _iacl 
copy _acl 
copy_iacl dir 
copy_ ~iael | _seg 
delete acl 
delete _iacl dir 
delete iacl seg 
list_accessible 


list _acl 
list _not_accessible 


list_iacl_dir 
list_iacl_ seg 


print_auth_ names 


set_acl 
set_iacl dir 


set_iacl_ seg 


add_search paths 
add_search rules 
attach lv 

change default _wdir 
change wdir 


delete _search_paths 


delete search rules 
detach_lv 


get_system_search_rules 


initiate 
list_ref_names 

new _proc 

print _default_wdir 
print proc auth 
print_search_paths 


print_search_rules 


print_wdir 
set_search_paths 


set_search_rules 
terminate 


walk subtree 


where 


compares segment ACLs with the initial ACL 

copies ACL from segment or directory 

copies a directory initial ACL 

copies a segment initial ACL 

removes an ACL entry 

removes an initial ACL for new directories 

removes an initial ACL for new segments 

lists segments and directories with a given 
access condition 

prints an ACL entry 

lists segments and directories to which user 
does not have a given access condition 

prints an initial ACL for new directories 


+ an * 
prints an initial ACL for new segments 


prints names of sensitivity levels and access 
categories for an installation 

adds (or changes) an ACL entry 

adds (or changes) an initial ACL for new 
directories 

adds (or changes) an initial ACL for new segments 


wa sine 


STORAGE SYSTEM, ADDRESS SPACE CONTROL 


adds one or more search paths to the specified 
search list 

allows users to change (insert) search rules 
dynamically 

calls the resource control package to attach 
a logical volume 

sets the default working directory 

changes the working directory 

allows user to delete one or more search panes 
from specified search list 

allows users to delete current search rules 

detaches logical volumes attached by the 
resource control package 

prints definitions of site-defined search rule 
keywords 

adds a segment to the address space of a process 

prints all names by which a segment is known 
to a process 

creates a new process with a new address space 

prints name of default working directory 

prints access authorization of the current 
process and current system privileges 

prints the search paths in the specified search 
list 

prints names of directories searched for 
segments referenced dynamically 

prints name of current working directory 

allows user to replace search paths contained 
in specified search list 

allows users to modify search rules 

removes a segment from the address space of a 
process 

executes a command line in all directories 
below a specified directory 

uses current search rules to locate and print 
pathname of a segment 
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where _search_paths 


FORMATTED OUTPUT FACILITIES 


cancel daemon_request 
compose 

dprint 

dpunch 

dump_segment 
list_daemon_requests 
move daemon request 


overlay 


print 


returns absolute pathname(s) of entryname when 
search list name and entryname are specified 


eancels a previously submitted daemon request 

composes formatted documents for production 
on various devices, including terminals 
and line printers 

queues a segment or multisegment file for 
printing on the high-speed printer 

queues a segment or multisegment file for ecard 
punching 

prints segment contents in octal, ASCII, or 
EBCDIC 

prints list of print and punch requests 
currently queued 

moves a request from one I/O daemon queue to 
another 

reads several ASCII segments and writes on 
user output I/O switch output that is the 
result of superimposing print -positions 
from each segment 

prints an ASCII segment 


LANGUAGE TRANSLATORS, COMPILERS, AND INTERPRETERS 


apl 

basic 

bind 

eancel _cobol_ program 


cobol 
ecobol_abs 


create data_segment 
display _cobol_run_unit 
expand_cobol_source 
fast 


format_cobol_ source 


fortran 
fortran_abs 


pl 
pl1_abs 
profile 


run_cobol 


invokes the APL interpreter 

compiles BASIC programs 

packs two or more object segments ee a single 
executable segment 

cancels one or more programs in the current 
COBOL run unit 

compiles COBOL programs 

submits an absentee request to perform COBOL 
compilations 

translates a create _data_segment source program 
into an object segment 

displays the current state of a COBOL run unit 

translates COBOL source program containing COPY 
and REPLACE statements to equivalent source 
program not containing these statements 

allows user to enter FAST subsystem 

converts free-form COBOL source to fixed-format 
COBOL source 

invokes the site's "standard" FORTRAN compiler 

invokes the site's "standard" FORTRAN compiler 
in an absentee job 

indents a PL/I source segment to make it more 
readable 

enters interactive Lisp subsystem, where Lisp 
forms can be typed at user's terminal and 
evaluated | 

compiles PL/I programs 

invokes the PL/I compiler in an absentee job 

prints information about execution of 
individual statements within program 

executes a COBOL run unit in a main program 
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set_cc 


set_fortran_common 
stop _cobol_run 


OBJECT SEGMENT MANIPULATION 


archive 
archive table 


bind 


date compiled 


attach audit 

change error_mode 
cumulative page trace 
debug 

display audit_file 
dispiay pliio_error 
dump segment 


general ready 
page trace 


probe 
profile 


progress 
ready 

ready_off 

ready _on 

reprint _error 

resolve linkage error 


trace 


trace stack 


INPUT/OUTPUT SYSTEM CONTROL 


assign resource 
eancel resource 


cancel daemon_request 
close file 


ecopy_cards 
copy_file 


sets carriage control transformation for 
FORTRAN files 

initializes common storage for a FORTRAN run 

terminates the current COBOL run unit 


packs segments together to save physical storage 

returns the names of specified archive 
components in specified archive segment 

packs two or more object segments into a single 
executable segment 

prints date and time compiled and compiler 
identifier for object segments 


DEBUGGING AND PERFORMANCE MONITORING FACILITIES 


SL 


sets up specified I/0 switch to be audited by 
the audit_ I/O module 

adjusts length and content of system condition 
messages 

accumulates page trace data 

permits symbolic source language debugging 

displays the file produced by the audit_ I/0 


module 

displays diagnostic information about PL/I I/0 
errors 

prints segment contents in octal, ASCII, or 
EBCDIC 


allows user to format ready messages 

prints ahistory of system events within calling 
process 

permits program debugging online 

prints information about execution of 
individual statements within program 

prints information about the progress of a 
command as it is being executed 

prints the ready message: a summary of CPU 
time, paging activity, and memory usage 

suppresses the printing of the ready message 

restores the printing of the ready message 

reprints an earlier system condition message 

satisfies linkage fault after a process 
encounters a linkage error 

permits the user to monitor all calls to a 
specified set of external procedures 

prints stack history 


assigns peripheral equipment to user 

cancels reservations made with the reserve 
command 

eancels a previously submitted print or punch 
request 

closes open PL/I and FORTRAN files 

copies card decks read by I/O Daemon 

copies records from an input file to an output 
file 
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discard output 


display _pllio_error 
dprint 
dpunch 


file output 
LO: Cal 


line length 
list_daemon_requests 
list_resource_ types 
list resources 

print 


print_attach table 


print_request_ types 
reserve resource 


tape_archive 
unassign resource 


vfile_ adjust 
vfile_ status 


COMMAND LEVEL ENVIRONMENT 


abbrev 
add_search_paths 
add_search_rules 


answer 
attach audit 


change default_wdir 
change _error_mode 


change wdir 
delete search paths 


delete_search rules 
detach_audit 
display audit file 
do 


exec com 


fast 
file output 


executes a command line while temporarily 
suppressing output on specified I/O 
switches 

displays diagnostic information about PL/I I/0 
errors 

queues a segment or multisegment file for 
printing on the high-speed line printer 

queues a segment or multisegment file for card 
punching 

directs terminal output to a file 

allows direct calls to input/output system 
entries 

allows users to control maximum length of output 
lines 

prints list of print and punch requests 
currently queued 

prints a list of all resource types described 
in a resource type description table (RTDT) 

lists peripheral equipment assigned to user 

prints an ASCII segment 

prints list of current input/output system 
switch attachments 

prints available I/O Daemon request types 

reserves resource(s) for use by the calling 
process 

performs a variety of operations to create 
and maintain a set of files on magnetic 
tape 

unassigns peripheral equipment assigned to user 

adjusts structured and unstructured files 

prints the apparent type and length of storage 
system files 


allows user-specified abbreviations for command 
lines or parts of command lines 

adds one or more search paths to the specified 
search list 

allows users to change (insert) search rules 
dynamically 

answers questions normally asked of the user 

sets up specified I/O switch to be audited by 
the audit _ I/0 module 

sets the default working directory 

adjusts length and content of system condition 
messages 

changes the working directory 

allows user to delete one or more search paths 
from specified search list 

allows users to delete current search rules 

removes audit_ from specified switch 

displays the file produced by the audit_ I/0 


moduie 
expands a command line with argument 
substitution ; 


allows a segment to be treated as a list of 
executable commands 

allows user to enter FAST subsystem 

directs terminal output to a file 
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gceos 


general ready 
get_system_search_rules 


LE 
line length 
memo 


new_proc 
on 


print _default_wdir 
print _search_paths 


print_wdir 
program interrupt 


ready 
ready _ off 
ready on | 
release 


repeat _query 


reprint _error 
resolve linkage error 


run 


set_search_paths 


set_search rules 
set_tty 


start 
stop run 


where _search_paths 


COMMUNICATION AMONG USERS 


accept_messages 
defer messages 


delete message 
immediate_messages 
print_mail 
print_messages 
read mail 


invokes GCOS environment simulator to run single 
GCOS job in user's process 

allows user to format ready messages 

prints definitions of site-defined search rule 
keywords 

conditionally executes a command line 

allows users to control maximum length of output 
lines 

allows users to set reminders for later printout 

creates a new process with a new address space 

establishes handler for specified set of 
conditions, executes imbedded command line 
with handler in effect, reverts handler 

prints name of default working directory 

prints the search paths in the specified search 
list 

prints names of directories searched for 
segments referenced dynamically 

prints name of current working directory 

provides for command reentry following a quit 
or an unexpected signal 

prints the ready message: a summary of CPU 
time, paging activity, and memory usage 

suppresses the printing of the ready message 

restores the printing of the ready message 

discards process history retained by a quit 
or an unexpected signal interruption 

repeats the last query by the command query_ 
subroutine 

reprints an earlier system condition message 

satisfies linkage fault after a process 
encounters a linkage error 

provides user with temporary, somewhat 
isolated, environment for execution of 
programs 

allows user to replace search paths contained 
in specified search list 

allows users to modify search rules 

prints and sets modes associated with user's 
terminal 

continues process at point of a quit or an 
unexpected signal interruption 

effects abnormal termination of run-unit 
created by run command 

returns absolute pathname(s) of entryname when 
search list name and entryname are specified 


initializes the process to accept messages 
immediately 

inhibits the normal printing of received 
messages 

deletes messages saved in user's mailbox 

restores immediate printing of messages 

prints all messages in a mailbox 

prints any pending messages 

provides a facility for examining and 
manipulating messages 
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send mail 

send message 

send message acknowledge 
send_message express 


send message silent 


who 


COMMUNICATION WITH THE SYSTEM 


eancel retrieval request 
check info_segs 
damaged _ sw_off 

damaged _sw_on 

help 

how_many_users 

enter retrieval request 
list_help 
list_retrieval requests 
move _abs_request 
no_save_on_disconnect 
print _motd 
save_on_disconnect 
volume_dump_ switch off 


volume dump switch_on 


who 


ACCOUNTING 


get_quota 
move quota 


resource _ usage 


transmits a message to one or more recipients 
sends message to specified user 

sends message and acknowledges its receipt 
sends message only if user will receive it 


immediately 

sends message but does not acknowledge its 
receipt 

prints list of users and absentee jobs currently 
logged in 


deletes request for a volume retrieval that 
is no longer needed 

ehecks information (and other) segments for 
changes 

resets damaged switch off for segments 

sets damaged switch on for segments 

prints special information segments 

prints the number of logged-in users 

queues volume retrieval requests for specific 
segments, directories, multisegment files, 
and subtrees 

displays names of all info segments pertaining 
to a given topic 

lists retrieval requests in the retrieval daemon 
queues 

moves a request from one absentee queue to 
another 

disables process preservation across hangups 
in user's process 

prints the portion of the message of the day 
that changed since last printed 

reverses effect of no_save_on_disconnect 
command 

turns off the specified volume dump switch of 
a segment 

turns on the specified volume dump switch of 
a segment 

prints list of users and absentee jobs currently 
logged in 


prints secondary storage quota and usage 

moves secondary storage quota to another 
directory 

prints resource consumption for the month 
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CONTROL OF ABSENTEE COMPUTATIONS 


cancel abs request 
cobol abs 


enter abs request 
fortran_abs 


how_Many_users 
list_abs_ requests 


move abs request 


win A 


MISCELLANEOUS TOOLS 


cale 
calendar 
canonicalize 


decode 
encode 
manage volume_pool 


memo 
merge 
progress 


sort 


cancels a previously submitted absentee job 
request 

submits an absentee request to perform COBOL 
compilations 

adds a request to the absentee job queue 

invokes the site's "standard" FORTRAN compiler 
in an absentee job 

prints the number of logged-in users 

prints list of absentee job requests currently 
queued 

moves a request from one absentee queue to 
another 

invokes the PL/I compiler in an absentee job 

invokes the runoff command in an absentee job 

prints list of users and absentee jobs currently 
logged in 


performs specified calculations 

prints a calendar page for one month 

ensures that contents of a segment are in 
canonical form 

deciphers segment, given proper coding key 

enciphers segment, given a coding key 

allows users to regulate use of a predefined 
set of volumes 

allows users to set reminders for later printout 

provides generalized file merging capability 

prints information about the progress of a 
command as it is being executed 

provides generalized file sorting capability 
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APPENDIX A 


USING MULTICS TO BEST ADVANTAGE 


You may, if you wish, treat Multics as simply a PL/I, FORTRAN, APL, BASIC, 
or COBOL machine, and contain your activities to just the features provided in 
your preferred programming language. On the other hand, much of the richness of 
the Multics programming environment involves use of system facilities for which 
there are no available constructs in the usual languages. To use these features, 
it is generally necessary to call upon library and supervisor subroutines. 
Unfortunately, a simple description of how to call a subroutine may give little 
clue as to how it is intended to be used. The purpose of this appendix is to 
illustrate typical ways in which many of the properties of the Multics programming 
environment may be utilized. 


When you choose a language for your implementation, you should carefully 
eonsider the extent to which you will want to go beyond your language and use 
system facilities of Multics which are missing from your language. As a well-known 
standard for completeness of that language (e.g., ANSI or IBM). However, in 
going beyond the standard languages, you will find that Multics supervisor and 
library routines are designed primarily for use from PL/I programs. This results 
from the fact that most of these routines are themselves implemented in PL/I. 
For example, if you plan to write programs which directly call the Multics 
storage system privacy and protection entries, in FORTRAN or BASIC, you have no 
eonvenient way to express such structures. Note that the situation is not hopeless, 
however. Programs which stay within the original language can be written with 
no trouble. Also, in many cases, a trivial PL/I interface subroutine can be 
constructed, which is callable from, say, a FORTRAN program, and goes on to 
reinterpret arguments and invoke the Multics facility desired. This is made 
possible by the Multics conventions which ensure that FORTRAN and PL/I programs 
ean communicate. (For more information, see the MPM Subsystems Writers' Guide.) 
Using such techniques, almost any program a standard call is performed, the 
argument pointer is set to point at the originally prepared for another system 
can be moved into the Multics environment. 


The examples which follow show that the effect of the mapping together of 
the main memory and secondary storage environments can range from the negligible 
(programs can be written as though there was a traditional two-environment system) 
to a significant simplification of programs which make extensive use of the 
storage system. Here are seven brief examples of programs which are generally 
simpler than those encountered in practice, but which illustrate ways in which 
online storage is accessed in Multics. 
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1. 


Internal Automatic Variables. The following program types the word "Hello" 
on four successive lines of terminal output: 


procedure; 
declare i fixed binary; 
do i= 1 to 4; 

put list ("Hello"); 


put skip; 
end; 
return; 
end a; 


The variable i is by default of PL/I storage class internal automatic: 
in Multics it is stored in the stack of the current process and is available 
by name only to program a and only until a returns to its caller. It is 
declared binary for clarity: although the default base for the representation 
of arithmetic data is binary according to the PL/I standard, as well as in 
Multics PL/I, some other popular implementations have a decimal default. 
There is no need for decimal arithmetic in this program, and binary arithmetic 
is faster. 


Internal Static Variables. The following program, each time it is called, 
types out the number of times it has been called since its user has logged 
in: 


procedure; 
declare j fixed binary internal static intial(0); 
J=j+; 


put list (j, "calls to b."); 
put skip; 

return; 

end b; 


The variable j is of PL/I storage class internal static; in Multies it 
is stored in b's static section (discussed in Section 2) and is available 
by name only to program b. Its value is preserved for the life of the 
process, or until b is terminated (by the terminate command, recompilation, 
etc.), whichever time is shorter. The "initial" declaration causes the 
value of j to be initialized at the time this procedure is first used in a 
process. 
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3-4. 


External Static. Suppose you wish to set a value in one program and have 
it printed by some other program in the same process: 


procedure;3 

declare z fixed binary external static; 
Zz Ns 

return; 

end ¢c; 


procedure; 

declare z fixed binary external static; 
put list (2); 

put skip; 

return; 

end d; 


In both programs, the variable z is of PL/I storage class external 
static; in Multics it is stored in a particular segment where all such 
variables are stored, and is available to all procedures in a particular 
process, until the process is destroyed. External static is analogous to 
common in FORTRAN, but with the important difference that data items are 
accessed by name rather than by relative position in a declaration. Program 
d above could be replaced by the following FORTRAN program: 


integer n 
common /z/ n 
print, n 

end 


Multics calls such data items external variables. There are commands 
(for example, list_external_ variables) to list, reinitialize, and otherwise 
deal with all the external variables used by a process. Each variable 
which is accessed in this form generates a linkage fault the first time it 
is used. Later references to the variable by the same procedure in that or 
subsequent calls do not generate the fault. 


Direct Intersegment References. The following program prints the sum of 
the 1000 integers stored in the segment w: 


procedure; 
declare w$(1000) fixed binary external static; 
declare (i, sum) fixed binary; 
sum = 03 
do i = 1 to hbound (w$,1)3 


sum = sum + w$(i)3 


end; 

put list (sum); 
put skip; 
return; 

end e;3 
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The dollar sign in the PL/I identifier "w$" is recognized as a special 
symbol by the PL/I compiler, and code for statement 6 is constructed which 
anticipates dynamic linking to the segment named w. Upon first execution, 
a linkage fault is triggered, and a search undertaken for a segment named 
W. If one is found, the link is snapped, and all future references will 
occur with a single machine instruction. The storage for array "w$" is the 
segment w. 


If no segment named w is found, the dynamic linker will report an 
error to the user and return to command level. At this point, it is possible 
to ereate an appropriate segment named w, and then continue execution of 
the interrupted program, if such action is appropriate. 


Reference to Named Offsets. The following procedure calculates the sum of 
1000 integers stored in segment x starting at the named offset u: 


L? procedure; 
declare x$u(1000) fixed binary external static; 
declare (i, sum) fixed binary; 
sum = 03 
do i= 1 to 1000; 
sum = sum + x$u(i); 


end; 

put list (sum); 
put skip; 
return; 

end f3 


Se ee eT eR Ee! 


The difference between this example and the previous one is that segment 
x is presumed to have some substructure, with named internal locations 
(entry points). To initially create a segment with such a substructure, 
the compilers and assemblers are used, since information must be placed in 
the segment to indicate where within it the entry points may be found. 
Unfortunately, the PL/I language permits specification of such structured 
segments only for procedures, not for data. The create _data.segment 
subroutine can be used in conjunction with the create data_segment (eds) 
command to create such data segments from PL/I data structures passed to it 
as parameters. The create data_segment command translates a CDS source 
program into a data segment (actually a standard object segment). A sample 
CDS source program, x.cds, is shown below: 


procedure; 
declare 1 x aligned, 
2 u(1000) fixed binary; 
declare create data_segment_ entry (ptr, fixed binary (35)); 


(overhead required to utilize create _data_segment_) 


call create data _segment_ <cds_args>; 
return; 
end x3 


A-4 AG90-03 


The ALM assembler can also be used to create a structured data segment, as 
shown by x.-alm below: 


External Reference Starting With a Character String. In many cases, a 
segment must be accessed whose name has been supplied as a character string. 
In those cases, a call to the Multics storage system is required in order 
to map the segment into the virtual memory and to obtain a pointer to it. 
The following program uses the supervisor entry hes $make ptr to perform a 
search for a segment of a given name, identical to that undertaken by the 
linker in the previous examples. 


procedure(string)3; 

declare string character(*) parameter; 

declare hes $make ptr entry (pointer, character(*), 
character(*), pointer, fixed binary(35)); 

declare null builtin; 

declare p pointer; 

declare ec fixed binary (35); 

declare hes_$terminate seg entry (ptr, fixed binary 
fixed binary (35));3 

declare com err entry options (variable); 

declare (i, sum) fixed binary; 

declare v(1000) fixed binary based(p); 

call hes_$make_ptr (null (), string, "", p, ec); 

if p= null then do; 
eall com_err_ (ec, "g", "“a", string); 


/* The segment should be terminated, since it was 
initiated */ 

call hes_$terminate_seg (p, 0, (0)); 

return; 

end g;3 


The PL/I null string value ("") indicates that it is not a named entry 
point in the segment to which a pointer is wanted, but a pointer to its 
Dase. Perhaps the segment does not even have named entry points. The PL/I 
null pointer value (null() ) and the zero passed by value ((0)) in the eall 
to hes $make ptr are relevant to its handling of error conditions and some 
of the parameters of the search for the segment. See the MPM Subroutines 
for a full description of the hes_$make ptr subroutine. 
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8. Reference to Segment Via Pathname. The following procedure finds a segment 
specified by an absolute or relative pathname given as an argument. Most 
Multics commands accept pathnames and find the segments they are to operate 
on in this fashion. This procedure also adds all the numbers in the segment, 
obtaining the number of entries in the array by using the bit count of the 
segment. 


h: procedure(string); 

declare string char(*); 

declare expand _pathname_ entry (char(*), char(*), char(*), fixed 
binary (35))3 

declare dn char(168), en char(32), ec fixed binary(35); 

declare com err entry() options(variable); 

declare hes $initiate count entry char(*), char(*), char(*), fixed 
binary(24), fixed binary(2), ptr, fixed binary (35))3_ 

declare null builtin; 

declare be fixed binary(24); 

declare p ptr; 

declare nwords fixed binary; 

declare i fixed binary; 

declare sum fixed binary (35); 

declare w (nwords) fixed binary(35) based (p);3 

declare hes $terminate_noname entry (ptr, fixed binary (35)); 

declare sysprint file; 

call expand _pathname_ (string,dn,en,ec); 

if ec “= 0 then do; 

err: call com_err_ (ec,"h","*a",string); 

return; 

end; 

call hes$initiate count (dn,en,"",bc,0,p,ec); 

if p = null then goto err; 

nwords = divide (bc, 36,17,0); 

sum = 0; 

do i= 1 to nwords; 

= sum + wli); 


call hes _$terminate_noname (p,(0)); 
put list (sum); 
put skip; 

end h; 


The expand pathname procedure is a library subroutine which accepts a relative 
or absolute pathname and returns the directory name and entryname ready for use 
by supervisor entries such as hes $initiate count. No search for the segment 
specified is undertaken in this case. Since the segment was initiated with a 
null reference name (third argument to hes $initiate count), the procedure is 
responsible for terminating it as well. 


Further improvements to this procedure are possible. It lacks the ability 
to handle several common error cases; if no argument is supplied, for example, 
the program will malfunction. Code to handle this possibility should be included, 
as well as code to handle the possibility of a zero-length input segment, or the 
possibility of a fixed point overflow. 
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APPENDIX B 


A SIMPLE TEXT EDITOR 


The sample program discussed in this appendix is a printing-terminal text 
editor similar to, but simpler than, Edm. (See Appendix D for a description of 
Edm.) It is a typical example of an interactive program which makes use of the 
Multiecs storage system via the virtual memory. In overview, the editor creates 
two temporary storage areas, each large enough to hold the entire text segment 
being edited; copies the segment into one of these areas, so as not to harm the 
original; and then, as the user supplies successive editing requests, constructs 
in the other area an edited version of the segment. When the user finishes a 
pass through the segment, the editor interchanges the roles of the two storage 
areas for the next editing pass. When the user is done with the editor, the 
appropriate temporary storage area is then copied back over the original segment. 
This example is not intended to be a model for designing or implementing text 
editors, but rather, an illustration of the techniques used in interactive Multics 
PL/I programs, particularly commands. 


For this example, a program listing as produced by the PL/I compiler is 
used. The program itself is derived from the edm command of Multics, and it 
exhibits several different styles of coding and commenting, since it has had 
many different maintainers. 


The program listing is preceded by several pages of comments on the program. 
The comments appear in the same order as the item(s) in the program that they 
comment on. Where possible, they refer to line numbers in the program listing. 
Unfortunately, programs do not always invoke features in the best order for 
understanding, so the following strategy may be useful: as you read each comment, 
if its implications are clear and you feel you understand it, check it off. If 
you encounter one which does not fit into your mental image of what is going on, 
skip it for the moment. Later comments may shed some light on the situation, as 
will later reference to other Multiecs documentation. Finally, a hard core of 
obscure points may remain unexplained, in which case the advice of an experienced 
Multics programmer is probably needed. Be warned that the range of comments is 
very wide, from trivial to significant, from simple to sophisticated, and from 
obvious to extremely subtle. 


Finally, some comments provide suggestions for "good programming practice". 

Such suggestions are usually subjective, and often controversial. Nonetheless, 

the coneept of choosing among various possible implementation methods one which 

has clarity, is consistent, and minimizes side effects is valuable, so the suggestions 

re provided as a starting point for the reader who may wish to develop his own 
style of good programming practice. 


You will also notice that some comments appear to be critical of the program 
style or of interfaces to the Multics supervisor. These comments should be 
taken in a spirit of illumination of the mechanisms involved. Often they refer 
to points which could easily be repaired, but which have not been in order to 
provide a more interesting illustration. Most of the points criticized are 
minor in impact. 
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The program listing appears after the commentary. 


Line number 


fifth unnumbered line 


3,4,5 


12 


The command "pli eds -map -optimize" was typed at the terminal. This 
line records the fact that the map and optimize options were used. 
The map line option caused a listing and variable storage map to be 
produced. A source segment named eds.pl1 was used as input; the compiler 
constructed output segments named eds.list (containing the listing) 
and eds (containing the compiled binary program.) 


No explicit arguments are declared here, even though eds should be 
called with one argument. Instead, the keyword "options (variable)" 
appears, which indicates that this program can be called with a variable 
number of arguments. This is a Multics extension to ANSI PL/I. Since 
eds is used as a command, it is a good human engineering practice to 
check explicitly for missing arguments; the PL/I language has no feature 
to accomplish this check gracefully. Library subroutines are available 
to determine the number and type of arguments supplied (see lines 
102-121). All Multics commands are declared and process their arguments 
in this way. 


It is common practice to include a short comment at the beginning of 
every program which briefly describes it. This should be followed by 
a comment or series of comments identifying the date of writing and 
original author, and the date, author and purpose of any subsequent 
modifications. This history, or "journalization" as it is called, is 
very helpful to others who may wish to modify the program in the 
future. 


To avoid errors when program maintenance is performed by someone other 
than the original coder, all variables are explicitly declared. This 
practice not only avoids surprises, but also gives an opportunity for 
a comment to indicate how each variable is used. 


One default which is used here (and is subject to some debate) is that 
the precision of fixed binary integers is not specified, leading to 
use of fixed binary(17). This practice has grown up in an attempt to 
allow the compiler to choose a hardware-supported precision, and in 
fear that an exact precision specification might cause generated code 
to eheck and enforce the specified precision at (presumably) great 
cost. In fact, the PL/I language does not require such checks by 
default (although they can be specified). Thus, it is usually wise to 
specify data precision exactly. In some cases (for instance, all of 
the fixed binary (21) variables used to hold string lengths), the 
compiler might attempt to hold these values in half-length registers 
were this precision not specified. 


However, a large class of variables which will contain "small or reasonable 
size integers" can still be conveniently declared with the 
implementation's default precision. 


All character strings in this program are declared unaligned, by the 
defaults of the language. Given the fact that the Multics hardware 
has extremely powerful and general string manipulation instructions, 
no advantage is to be gained in speed or length of object code by 
declaring strings (when they are over two words, or eight characters, 
long) with the aligned attribute. 


Therefore, almost all supervisor and library subroutines which accept 
character string arguments require unaligned strings. By the rules of 
PL/I, aligned and unaligned strings may not be interchanged as parameters, 
and thus, there is incentive to avoid aligned character strings in all 
cases. 
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15 


23,24 


24,50 


43 


56 


All line buffers are designed to hold one long typed line (132 characters 
for input terminals with the widest lines), plus a moderate number of 
backspace/overstrike characters. To support memorandum typing, the 
buffers permit a 70-character line which is completely underlined. 


By use of temporary segments as work areas (see line 149), an almost 
unlimited number of nearly infinite work-variables can be constructed, 
virtually avoiding the "fixed length buffer" problem. However, the 
acquisition and maintenance of such segments are not as cheap as PL/I 
automatic variables, and judgement should be exercised as to where 
traditional "fixed length" variables are appropriate. 


The variable named "code" has precision 35 bits, since it is used as 
an output argument for several supervisor entries which return a fixed 
binary(35) value. Almost all supervisor and library subroutine entries 
return an "error code" value, which indicates the degree of success of 
the operation requested. The values of system error codes require 35 
bits. It would seem appropriate, on a 36-bit machine, to use fixed 
binary(35) declarations everywhere. However, use of fixed binary(35) 
variables for routine arithmetic should be avoided since, for example, 
addition of two such variables results in a fixed binary(36) result, 
forcing the compiler to generate code for double precision operations 
from that point on. We must be careful of the PL/I language rule 
which requires the compiler to maintain full implicit precision on 
intermediate results. 


Legal PL/I overlay defining can be an extremely powerful tool for 
increasing the readability and maintainability of code. . The variable 
"commands" is declared here as occupying the same storage as the variable 
"buffer", but only being as long as that part of it which contains 
valid characters, as defined by the value of "count". Thus, we need 
only write "commands" when we want the portion of "buffer" that has 
valid data in it, instead of "the substring of 'buffer' starting at 
the first character for 'count' characters." 


All editing is done by direct reference to virtual memory locations. 
The variable "from_ptr" is set to point to a source of text, and the 
based variable "from_seg" is used for all reference to that text. The 
number 1048576 (two to the twentieth power) is the largest possible 
number of characters in a segment. 


The general operation of the editor is to copy the text from one 
storage area to another, editing on the way. The names "from_seg" and 
"to_seg" are used for the two storage areas. 


One set of supervisor interfaces calls for 24 bit integers; this 
declaration guarantees that no precision conversion is necessary when 
calling these interfaces. (See line 133.) 


The PL/I language provides no direct way to express literal control 
characters. The technique used here, while it clutters the program 
listing, at least works. The string is typed as a quote, a newline, a 
tab, a space, and a quote. This order is used because it produces the 
least ambiguous printed representation; for instance, had the tab and 
space been reversed, it would not be possibleto distinguish by observation 
between the space, tab sequence and a single tab. 


PL/I does not provide any "named constant" facility, either. The Multics 
PL/I implementation allows the "options (constant)" attribute for internal 
static variables, which instructs the compiler to allocate the variable 
in the pure (unmodifiable) portion of the object segment. fThis is 
advantageous for three reasons: first, if an attempt is made to modify 
such a variable, the hardware will detect an error, thus checking and 
enforcing its "constant" use; second, it allows the variable to be 
shared between processes, conserving storage; third, it is an indication 
to others reading the program that a "named constant" is intended. 
These "constants" are customarily given all uppercase names, as an 
additional hint to the reader of their constant nature; this is a 
standard Multics PL/I convention. 
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64,77 


65 


65 


67 


70 


90 


92 


102 


103 


Subroutines com_err_ and ioa_ are called with a different number of 
arguments each time, a feature not normally permitted in PL/I. The 
Multics implementation, however, has a feature to permit such calls. 
The "options" clause warns the compiler that the feature is used for 
this external subroutine. 


All subroutines other than com err and ioa are completely declared 
in order to guarantee that the compiler can check that arguments being 
passed agree in attribute with those expected by the subroutine. Warning 
diagnostics are printed if the compiler finds argument conversions 
necessary. (All of the subroutines used by this program are described 
in the MPM Subroutines Manual. 


The procedure cu (short for command utility) has many different entry 
points. The Multics PL/I compiler specially handles names of external 
objects which contain the dollar sign character. The dollar sign is 
taken to be a separator between a segment name and an entry point name 
in the compiled external linkage. Thus, this line declares the entry 


point name arg ptr in the segment named cu_. 


For many procedures, the segment name and entry point name are identical, 
so the compiler also permits the briefer form cv_dec_, which is handled 
identically to ev_dec $cv_dec . 


The hardcore (ring zero) supervisor entries (hardcore gates) are all 
easily identifiable since they are entered through a single interface 
segment named hes_. Segment hes_ consists of just a set of transfers 
to the subroutine wanted. A transfer vector is used to isolate, in 
one easily available location, all gates into the Multiecs supervisor. 
(There are in fact hardcore gate segments other than hes _, but you 
will probably not have occasion to deal with them.) For a discussion 
of the ring structure and hardcore gates, see the MPM Reference Guide. 


The program will need to know what I/O switches will be used in order 
to perform certain I/0 operations. I/O switches are the general 
source/sink I/0 facility of Multics. Multics PL/I programs manipulate 
I/O switches as PL/I pointer values. The two external variables declared 
on this line contain the pointer values identifying the standard terminal 
input and terminal output switches. 


As mentioned above, system error codes are returned by most supervisor 
and library subroutine entries. In one case, we will need to know if 
a specifie error (see line 142) was returned by a supervisor entry. A 
segment (error table ) exists which has entry point definitions for 
external static variables (see Appendix A) containing all the possible 
values that can be returned as errors by system routines. The variable 
error table $noentry contains the value returned as an error code by 
system routines to indicate that "the entry you specified in the directory 
you specified does not exist". 


The first order of business is to determine how many arguments were 
supplied to the command, and also to find out whether the command was 
called properly. This is done by calling a library subroutine. 


If the error code from cu_$arg' count is nonzero, it means that the 
program which called cu_$arg_ count was not invoked as a command. This 
usually indicates attempted use as an active function, which is invalid 
for eds. 
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125 


134 


The library subroutine com_err_ is called to print out the error message 
describing the invalid call. It produces an English explanation 
associated with the error code, which is obtained from a system-wide 
table (the error_table_). It also causes terminal output to be produced 
even if the user is temporarily diverting output to a file. In general, 
ecom_err_ should be called to report all command usage and operation 
errors. The output from such a call looks like this: 


eds: This command cannot be invoked as an active function. 


A Multies command exits simply by returning to its caller. (See also 
line 437). It should, however, clean up allocated storage, terminate 
segments, and return temporary segments if it needs to. In general, a 
program should do exactly the same things when it exits normally as 
its cleanup handler does. These actions are omitted for this return 
(and the next) because the program has yet to do anything which would 
require cleaning up, and because the variables which would inform the 
cleanup handler of its job have not yet been set. (See lines 133-134.) 


The eds editor must be invoked with exactly one argument. If it is 
not, we wish to print a message describing what was wrong, and suggesting 
the proper usage. This message is produced by picking an appropriate 
standard error table code to describe the error, and assigning it to 
code. All the standard error_table_ codes are listed in the MPM Reference 
Guide, Section 7. 


The com_err_ subroutine, as well as the ioa_ subroutine (See line 
162), allows substitution of parameters in its message. The "“a" string 
here is used to get the command name into the error message. It is 
done this way, rather than simply putting "eds" in the message, to 
make it possible to change the name of the program by changing only 
the declaration of MYNAME. 


After verifying that the right number of arguments (one) was supplied, 
we access the argument. As pointed out above, this is done via library 
subroutine rather than PL/I parameter passing. Since the command argument 
is nominally unlimited in length, cu_$arg ptr returns a pointer to the 
argument as stored by the command processor, and its length. The 
based variable "sname" will describe the argument once this pointer 
and length are obtained. The last argument is a zero, passed by value, 
because it is known that there is exactly one argument, and there is 
therefore no reason to receive or check the error code. This should 
only be done when it is guaranteed that no error can arise from the 
eall, since it will otherwise result in faults. 


We must now convert the argument to a standard (directory name, entry 
name) pair. The subroutine expand pathname implements the system-wide 
standard practice of interpreting the typed argument as either a pathname 
relative to the current working directory, or an absolute pathname 
from the root, as appropriate. 


The program will soon acquire (on line 149) a process resource, namely 
two temporary segments from the process's pool of temporary segments. 
When the program is finished executing, it will return them (line 589) 
to the pool. However, the program may be interrupted (perhaps by a 
QUIT, or a record quota overflow), and the user may abandon its stack 
frame (perhaps via the "release" command). In this case, it would 
seem that the program would not get a chance to return its "borrowed" 
resources. However, Multics defines the "cleanup" condition, which is 
signalled in all procedures when their stack frame is about to be 
irrevocably abandoned. (Refer back to Figures 5-1 and 5-2.) The handler 
for the cleanup condition invokes the procedure "cleanup", which 
relinquishes these resources. 


B-5 AG90-03 


139 


141 


142 


143 


149 


The array "“temp_segs" is initialized to null pointer values before 
establishing the cleanup handler, so that the content of the array is 
well defined at all times. (The release temp segments _ subroutine checks 
for null pointer values, and performs no action if it encounters them.) 
Otherwise, if the cleanup handler were invoked before the temporary 
segments were acquired, the pointer array would have undefined, probably 
invalid values, and the call to release the temporary segments would 
have unpredictable results. 


The cleanup handler is established before the temporary segments are 
reserved. This sequence guarantees that there will be no "window" in 
which the program can be abandoned between the time that the segments 
are acquired and the time that the cleanup handler is set up. 


The supervisor entry point hes $initiate_ count is invoked to map the 
segment specified by the (directory name, entry name) pair into the 
process's virtual memory. It returns a pointer to the segment, which 
it constructs from the segment number by which the segment was “mapped 
into the virtual memory of the process (made known). If the segment 
was already "known", i.e., in the process's address space, the segment 
number from the existing mapping will be used to create a pointer to 
return. Refer to the MPM Reference Guide, Section 4, for details. 


The PL/I null string ("") isa special signal that no (possibly additional) 
reference name is to be initiated for the segment. 


Unfortunately, the zero/nonzero value of the return code from 
hes $initiate_ count cannot be used to check whether the initiation 
(mapping into the address space) succeeded. In the particular case of 
this subroutine and hes $initiate, a nonzero error code is returned in 
the ostensibly successful case of the segment having already been in 
the address space or the process, a case which is rarely an error. 


These two subroutines are defined to return a nonnull pointer value if 
and only if the segment has been successfully mapped into the address 
space, whether by prior act or anew. Thus, testing the return pointer 
for the PL/I null pointer value is the appropriate test for success. 


The editor (eds) will create a new segment (see line 496) if an attempt 
is made to edit a segment which does not exist. By comparing the 
value of the error code returned from hes_$initiate count with the 
system error code stored in the variable error table _$noentry, we can 
differentiate the case of failure to initiate simply because the segment 
did not exist from all other cases (e.g., incorrect access to the 
segment specified). 


The pathname subroutine is used here to return a string, which is 
then substituted into the message produced by com_err_, which is the 
representation of the pathname. This cannot be done by simply 
concatenating the dir_name, a ">", and the entry_name, since if the 
dir name were ">" (the root directory), this would result in an invalid 
pathname containing the sequence ">>". 


A pool of segments in a process directory is maintained by the 
get_temp_ segments - and release temp segments _ subroutines. These 
segments are doled out to commands and subsystems which request them 
(via get_temp segments ) and it is expected that they will be returned 
to the pool when there is no further use for them. This facility 
avoids the need for user programs to create and delete (or attempt to 
manage or share) segments needed on a "Seratch" or "temporary" basis 
(for work areas, buffers, etc). Segments obtained from this facility 
are guaranteed to contain all zeros (truncated) when obtained. 
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The number of segments to be obtained is determined by get temp segments 

from the extent of the pointer array parameter. The name of the subsystem 
is passed to get_temp_segments_ both to facilitate additional checking 
by release temp segments, and to support the list_temp_segments command, 
which describes which subsystems ina process are using temporary segments. 


If the segment specified on the command line does not exist, the editor 
is to assume that it is creating a new segment, and go into input 
mode. The value of the variable "source ptr" will be null if this is 
the case. 


The ioa_ subroutine is a handy library output package. It provides a 
format facility similar to PL/I and FORTRAN "format" statements, and 
it automatically writes onto the I/0 stream named user_output, which 
is normally attached to the interactive user's terminal. When used as 
shown, it appends a newline character to the end of the string given. 
Programmers who are more concerned about speed and convenience than 
about compatibility with other operating systems use ioa_ in preference 
to PL/I "put" statements, because ioa is cheaper, easier to use, and 
far more powerful. ~ 


The formatting facilities of ioa are used in a simple way in this 
example. The circumflex ("*") in the format string indicates where a 
converted variable is to be inserted; the character following the 
circumflex indicates the form (in this case, a character string) to 
which the variable should be converted. The first argument is the 
format string, remaining arguments are variables to be converted and 
inserted in the output line. 


The storage system provides for every segment a variable named the 
"bit count". For a text segment, by convention, the bit count contains 
the number of information bits currently stored in the segment. The 
bit count of the segment being edited was returned by hes $initiate_ count 
(hence its name) on line 139. 


This statement converts the bit count to a character count. Note that 
we have here embedded knowledge of the number of hardware bits per 
character in this program. 


The PL/I language specifies that the result of a divide operation 
using the division sign is to be a scaled fixed point number. To get 
integer division, the divide builtin function is used instead. Note 
that the precision of the quotient is specified to match its size. 


Here, we invoke some of the most powerful features of the Multics 
virtual memory. This simple assignment statement copies the entire 
source segment to be edited into the temporary buffer named "from_seg". 
A single hardware string-copy instruction is generated for this code, 
copying data at processor speed. The string-copy instruction may be 
interrupted by page faults on either "source seg" or "from_seg" several 
times; after allocating or reading the required page, the instruction 
is restarted where it left off. Note that we are regarding the entire 
text segment as a simple character string of length "size". We may 
regard it this way because the storage representation for permanent 
text segments is, by convention, identical to that of a PL/I nonvarying 
character string. 


Be sure to read the comments embedded in the program, too. 
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The standard I/0 system is being invoked to read a line from the 
user's terminal. The line is read from the I/0 switch identified by 
the external pointer iox_$user_input. Although passing the buffer to 
be used as a character string would be more convenient, this set of 
interfaces was designed with maximal efficiency in mind, and this form 
of call is more efficient. Note that it would also be safer than 
passing a pointer to the character string, since that would allow PL/I 
to check that an appropriate character string was being passed, as 
opposed to a pointer, which can point to any data type. This design 
demonstrates the frequent tradeoff between efficiency and convenience. 


Subroutine iox_$get_line is often used for input rather than the PL/I 
statement "read file (sysin) into ...", again because of efficiency 
and error-handling considerations. The PL/I facility ultimately calls 
on the Multics iox_ package anyway. (Again, if you wished to write a 
program which would also work on other PL/I systems, you would be 
better advised to use the PL/I I/0 statements instead.) 


It is highly unlikely that a call to read a line from the terminal 
will fail. Nevertheless, in cases of people debugging their own extensions 
to the Multics I/O system (a practice intended by the designers of the 
I/O system), it can occur. It is reasonable to abort the entire editor 
in this unlikely case rather than repeating the call: presumably that 
would repeat the error too. 


For the sake of human engineering, the editor ignores blank command 
lines. Since complete input lines from the typewriter end with a new 
line character, the length of a blank line is one, not zero. 


The code to isolate a string of characters on the typed input line is 
needed in four places, so an internal subroutine is used. This subroutine 
is not recursive, which makes it possible for the compiler to construct 
a one-instruction calling sequence to the internal procedure. Certain 
constructs (e.g., variables of adjustable size declared within the 
subroutine) will force a more complex calling sequence. For details, 
you should review the documentation on the Multics PL/I implementation, 
contained in the Multics P1/I Language Specification, Order No. AG94. 


Although the dispatching technique used here appears costly, it is 
really compiled into very quick and effective code -- 2 machine 
instructions for each line of PL/I. For such a short dispatching 
table, there is really no point in developing anything more elaborate. 
If the table were larger, one might use subscripted label constants 
for greater dispatching speed. 


Human engineering: the typist is forced to type out the full name of 
the one "powerful" editing request which, if typed by mistake, could 
cause overwriting of the original segment before that overwriting was 
intended. 


Whenever a message is typed which the typist is probably not expecting, 
it is good practice to discard any type-ahead, so that he may examine 
the error message, and redo the typed lines in the light of tnis new 
information. 


The general strategy of the editor is as follows: lines from the 
typewriter go into the variable named "buffer" (accessed as "commands") 
until they can be examined. Another buffer, named "line buffer" (accessed 
as "line") holds the current line being "pointed at" by the eds conceptual 
pointer. Subroutine "put" copies the current line onto the end of 
to seg, while subroutine "get" copies the next line in from_seg into 
the current line buffer. 


The procedure get_num sets up the variable "n" to contain the value of 


the next typed integer on the request line. Such side-effect communication 
is not an especially good programming practice. 
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The delete request is accomplished by reading lines from from seg, but 
failing to copy them into to_seg. If deletion were a common operation, 
it might be worthwhile to use more complex code to directly push ahead 
the pointer in from_seg, and thus avoid a wasted copy operation. 


More side-effect communication: the variable "edct" is always pointing 
at the last character so far examined in the typed request line. 


All movement of parts of the material being edited is accomplished by 
a simple string substitution, using appropriate indexes. 


The locate request is accomplished by use of the index builtin function, 
used on whatever is still unedited in from_seg. 


A negative number in the next request results in moving the conceptual 
pointer backward. The resulting code is quite complex because the eds 
editing strategy requires interchanging the input and output segments 
before backward scanning, so that the backward scan is with regard to 
the latest edited version of the segment. 


This code to search a character string backward is recognized by the 
compiler as such. Extremely efficient object code to search the substring 
backward is generated, using a single hardware instruction. No copies 
are made in this fairly expensive-looking statement: it is, in fact, 
cheap. Combinations of reverse, index, substr, search, verify, etc. 
that seem like they ought to generate efficient code in fart usually 
do. The -profile control argument and the profile command are useful 
tools for discovering where inefficient code is causing performance 
problems. 


Before exiting from the editor, the temporary segments should be returned 
to the temporary segment manager, and the segment that was initiated 
terminated. 


Another human engineering point: since the user may have typed several 
lines ahead, the error message includes the offending request, so that 
he can teli which one ran into trouble and where to start retyping. 


Note a small "window" in this sequence of code. If the editor is 
delayed (by "time-sharing") between lines 468 and 469, it is possible 
that the message on line 468 will be completed, and the user will have 
responded by typing one or more revised input lines, all before line 
469 discards all pending input. Although in principle fixable by a 
reset option on the write call, Multics currently provides no way to 
cover this timing window. Fortunately, the window is small enough 
that most interactive users will go literally for years without 
encountering an example of a timing failure on input read reset. 


Note the practice of copying data into the original segment, setting 
its bit count, and truncating it in that order. This provides for 
maximal data being saved should there be a system failure between any 
two lines. Common sense seems to indicate this order as "maximally 
safe", and analysis of the data involved will demonstrate this as 
well. 


The input and output editing buffer areas are interchanged by these 
three statements. Here is an example of iocaiizing the use of pointer 
variables to make clear that they are being used as escapes to allow 
interchange of the meaning of PL/I identifiers. 


The I/O system provides this entry point to perform control operations 
(e.g., "resetread") upon the objects represented by I/O switches. 
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This editor considers typed-in tab characters to be just as suitable 
for token delimiters as are blanks. Ideally, tab characters would 
never reach the editor, having been replaced by blanks by the typewriter 
input routines. Such complete canonicalization of the input stream 
would result in some greater simplicity, but would require a more 
sophisticated strategy to handle editing of text typed in columns. 


The PL/I search and verify builtins, which are quite useful in 
circumstances like this (parsing lines), are compiled into very efficient 
single-instruction hardware operations by the Multics PL/I compiler. 


The cv_dec_ library routine is used here rather than a PL/I language 
feature, because cv_dec_ will always return a value, even if the number 
to be converted is ill-formed (in which case it returns zero). Thus, 
the editor chooses not to handle ill-formed numbers. Had it wished to 
check for them, it could have used the cv dec check subroutine. PL/I 
language conversion would cause an error signal which must be caught 
and interpreted lest PL/I's runtime diagnostic appear on the user's 
console. Thus, eds retains complete control over the error comments 
and messages which will be presented to the user. Such control is 
essential if one is to construct a well-engineered interface which 
uses consistent and relevant error messages. 


The cleanup procedure calls the release temp segments _ subroutine to 
release the temporary segments acquired earlier. A binary zero is 
passed to release temp segments by value (by enclosing it in parentheses) 
because the cleanup handler has no use for an error code. Cleanup 
procedures should never print messages, even error messages, because 
they are only invoked when exiting a procedure. There is no corrective 
action the user can take. 


If the segment edited was not known before editing it, it should be 
unknown after the editor finishes as well. The supervisor maintains a 
reference count for each segment inthe process. This count is incremented 
by the call to hes _$initiate and decremented by the call to 
hes $terminate_noname. If the count goes to zero (i-e. the segment 
was made known by the editor), then the segment is made unknown. 
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4RG.0 Suhroutines, ov Someone Else x/ 
xf 
fixed binary? /x Number of command line arguments */ 
chapacter (43 /x ‘olds break char for change */ 


fixed hinary? 


eharacter 
Sit €1);> 


(210); /x Tyrewriter input buffer, */ 


fixed binary (35)3 


enaracter 


fixed >ymary ( 
fixect binary ¢ 


(count) hased Cadar (puffer)); 


/x Valid nortion of buffer */ 


fixacd hinary? 


character 
cnaracter 
potnter; 
nointer; 
character 


nit €4);7 


fixed hinary 
fixed hinary 
fived hirary 
fixer hingry 
fjxac hirary 
fixed binary 
fixer binary 


ehnaracter 
enaracter 


fixed hirary? 


Pld; 4x Valid length of data in "buffer " */ 
Aid; 
C165); ‘x Directory containing segment */ 
(32)? 


‘x Temporary pofnter holder, «/ 

/* Pointer to current from iseq, */ 
(1948576) hased (fromipter)s 

f/x Editina fs from this segment. */ 


(103 

(P12? 

(P13; 

C210; 

(71); 

(71); 

C?1)3 

(jinel) kased Caddr (line buffer) )3 

C210)% /x Holds line currently being edited. */ 
Je Jenath of "line" */ 


fixed Simery? 
fixed bhimery C1); 
fixed timary (2135 


enaracter 


fixed hinary (2133 fx 


rointer; 


fixed hinary (eu)? /* 


rointer; 
character 


Aajmension 
ecnaracter 
ehapracter 
cehapacter 


nointer? 


/* Source name */ 
Length of source segment name. */ 
/x Pointer to source seaqment name, */ 
Holds seament bit length, */ 
/x Pointer to source seq, */ 
(1%48575) based fsnurcecptr)$ ; 
/x Outside seament for read or write, */ 


Csname_ltn) hased (Csnamerptr)7 


(2) nrointer; 
C230)5 /x Puffer to hold outout of change. */ 
Cey3 /x Holds. next item on typed line */ 
fiN4’575) ased (teloter)? 

/x Editina is to this segment, */ 

/x Pointer to tolseaqa. */ 


AG90-03 


deciare 
")? 


declare 
declare 
/k 


declare 
declare 
declare 
declare 
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declare 
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AL character (1) static ootions (constant) initial ¢*" 
wHITESPACE character (3) static ontions Ceonstent) initial ¢* 

");, /* ML TAB SPACE x/ 
MYNAME character £3) static ootions (constant) initial ("eds"); 


external subroutine declarations, */ 


comverr_ entry options fvariable)? 
culfargucount entry (fixed oinary, fixed binary (35))3 
cultarg ptr entry (fixed sinary, pointers, fixed binary (21). fixed binary (35))3 
cv_dec_ entry (character (*)) returns (fixed binarv(35))% 
expand ivathname entry Ccharacter (*), character (*), character (*), fixed binary (35))? 
get _temp_seaments_ entry (character (*), mointer dimenston (%), fixed binary (35)); 
hes Sinitiate count entry (character (*)-+ character (%)s character (*), fixed binary (24), 
fixed binary, pointer, fixed binary (35));3 
hes _S$make seg entry (character (*), character (%), character (*), 
fixed bin (5), otr, fixed hinary (35))? 
hes_Sset_be_seg entry Cpninter, fixed hinmary (24), fixed binary(35))? 
hes Sterminate_nonare entry Crointers fixed hinmary (35))? 
hesUitruncate seg entry (cointere fixed binary (19), fixed binary(35))3 
joal entry ootions (variahle)s 
jox_Seontro} entry Coointers cnaracter (x), pointer, fixed binary (35))3 
iox_Saet_line entry Coointers pointer, fixed binary C2i1)- fixed binary (21), fixed binary 
jex_Seut_chars entry (pointer, sointer, fixed sinsry (24), fixed Simary (35))3 
pathname_ entry (character (*)+ character (*)) peturns (character (168))3 


release_teamo_seoments_ entry (character (*), mointer dimension (*), fixed binary (35)); 


cleanup condition? 
(addr, divider finder, lenaths, nuil,s reverse, search, substre verify) 
huiltin; 


fe =6Fyxternal data */ 


declare 
declare 
declare 
declare 


Cjiox Suser_loutout, fox tuser_linput) cointer external static? 

error table Snoaroa fixed binary (35) external static; 
error table _Snoentry fixed binary (35) external static} 
error table Stoo lmanyTargs fixed binary (35) external static; 
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if code *= 9 then do? 
call comlerr_ (eode, 
return, 
enc: 


then code 


5 


if aralcount = j 
else if aralecunt = 
elee cove = 


= Qo? 
then coce = er 
error _tehieclltoo many arcs? 


PRARRPA 


*/ 


was Given */ 


coca); 
/x Not called as a command x/ 


MEMAYE) | 
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ror_tablel%noarg? /*x Arrpqument is missing */ 
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call comoerr_ (eoder Mritabie "“/Usanet*=*3— <PATH>", MYNAMF) 3 
PeLUPN; 
enc: 
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/e Initiate the source seomert. */ 
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ean ups 


call nes_isinitiate count (dir_nanme, entrvonamer "", sourceccounts O, source ptr, code)? 
/k Initiate the seament */ 
if sourcalnotr = aul] (3 
then if cece “= erroar_taclte _Sroentry then doz/* Problem or Just new seq? */ 
call cemlerrl Conde, iY¥N4ME, "“famnet access *a", pathname, (dirname, entry name) )? 
peturn? 
eng? 
(* Set us suffer Sennents. xf 
call yet ltene_serments. (.YLfeF, temolseas, code); 
tf coge *= yy ther do? 
call comlerr_ (comer “rt htE, "Cannot cet temporary seaments.")} 
call clear vung? 
return; 


ond; 
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call inal ("%*a" Kat an eait Request", 
call resetread? 
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call jieal f"Trputr. "2: 
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tf substr Coonmmancs, iv 1) = "2" 6 Count 


eubstr (source _seue 


adagr (Couffer), 


substr fcommands,s 


adde (puffer), 


/e Initialize buffer control vars, */ 


entry_lname)} 


/x change hit count to char count */ 
1, csize); 
/*x Move source seoment into buffer. 


Tength (huffer), count, code} 


"Ercor reading input line"); 


fe Ff mull 
/* 
te 


line then get another line, 
Set up counter to scan this tine. 
Identify next token, */ 


lr length (commands)? = 1))37 


fx print word input */ 


length (buffer), counts code)? 


reading inout=mode line.")} 
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check for mode change */ 


move ljne inputted into intermediate storage */ 
repeat “til "8 x/ 


do for each line to be deleted */ 


nullify last line */ 


Add current line to outout segment */ 
This is also the retype request, */ 


add replaced line x/ 


save where you are */ 
once for mach ni */ 
check for eof */ 

NL 

locate end of line */ 

no ml (eof) print eof */ 


set to no line */ 
m+ 1, csize = m)?} 
move in top of file x*/ 


set pointers */ 


increment Jj by length of line */ 
set pointers and move in too of file */ 
put working line fn line */ 


(fromisegs m + 1, jindf = linel = m3 
fill rest of file */ 


/* check for plain "] NL® x/ 
Skin delimiter, */ 
initjalize mointers for index type search */ 
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m = ind; 
me 2s esize = ind fs 


call put? 
tf (esize = 9) | (mn <= 0) then do; 
call switch? 
if j > 0 then n = j = 1! 
else n =f; 
mp JT os NG 
end; 


1 = index fsubstr (fromisea, indf + 1, n), 


if i *s 0 then ao; 


k = index (reverse fsuostr (from_sea, 


if & *= 9 then k = indf + ij «© 


if J = 4% ther jnof = csize; 
else indf = j + «? 
supstr Ctolsec, inact + ly Kk = 


linel = ingf = k; 
ndt + k = m? 


ned: 
go to printi; 
end; 
cali coov; 
call switch, 
90 to next? 


LR REKEKEKEKKK DPN REKRKEKEK KS 
prints call get lnunir 
tf Limel = 0 then do? 
call joa ("Ne linew"); 
go to noline; 
end? 


q 
substr (fromusegr * + 1, 


ko + 1 
j = index (substr (fremisea, k + 1, 


linel); 


csize = 


suposte (commands, edet, lenath (commands) = edet)); 


/* if found then do x*/ 


indf + i))- NLD 


/e k = index of NL x/ 


k), NLI? /e find end of line */ 


a) = subhstr (from segs mitt, k= mi 


/x move in top of file */ 


/*x put found line tn line */ 


/* print found line if wanted */ 


fk get next command */ 


/x print jndication of no tines */ 


printls: cal} jiox Sout uchars Ciox utuserloutput, addr (jine), length (line), code)s 


7# code *= 0 then dot 


call comlerr. (coder "{NAME, “Prohlem a«riting editor oytout")? 


go to finish; 
end; 


noline: nen i] 
if n= 0 then co to next? 
call pute 
call get? 
ao to erintl:? 


fk KKKKEHKEEK Change KkKEKe KKK */ 


located = 4; 
if count = 2 then do? 
badusyntax?! 


chances: 


count = count = 1? 
call joa. ("Irproner: 
call resetread; 

go to next; 


an " 


end; 
brkil = edct + 27 
“ break = substr (commands, eact + ip 


a", conmands)? 


J)5 


/x write the line */ 


/x any more to of printed? x/ 


7x Strip NL off "commands " */ 


/* Pick up the delimiting character. */ 
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XS 
336 
337 
238 
239 
wun 
341 
Bue 
Rar 
Zu 
3qh 
a4 
247 
Zar 
uO 
35¢ 
351 
252 
352 
son 
355 
354 
297 
458 
359 
369 
361 
Rar 
3G% 
Boa 
Boe 
Boh 
307 
26% 
R09 
a7" 
371 
27? 
272 
zza 
275 
276 
377 
372 
379 
339 
351 
5H? 
383 
384 
Bas 
RBA 
307 
BHR 
3B¢ 
390 
391 
399 
393 
Bye 


MAAS 


cht: 


cn; 


Cort? 


Sxkineh?t 


ee 


= tinder (Csubster 
f i = 6 
= index (substr 


—s 


fooanmands, 


feoumandss 


beK1), 


then m0 te hadusystax? 
joroor 


krpeak)? 
Kid, break)? 


= sibster Coommands, 


enstn (Tine)) = 
é 


sucstr (Cconmands, 


= substr (line, 


s j “i 


(line) = m= 


if j = 9 then ft = length (Ceommands) 
eget = edct + § + jf + 9; 
oglobpsw = "ANH; 
ys so 1; 
call setlteKnen? 
if tkn “= "7 " tren da; 
if tkn = "g" then colobsw 
else call cv onus; 
gO to nY¥arat 
end; 
if linel = &@ then co te skipech? 
cnanzes_ occurred = "ON; 
tp Je 1 = if 
if i = | then co: 
chanves occurred & "1"yo27 
Jocates = 1? 
Ssuostr ftlim, le i = 14 
Supstp ftlin, j, 1 
ij = J + lined - 1 
1 = j + jinel + i: 
go to cmrt, 
enn? 
bh = index fsunste Cline, re 
if « *2 % then ce; 
sustr (thin, it, « 7 4) 
Supste (tlin, jf # & wf 
i Dm Fe + J = ECF? 
jis dj t+ ke ej 7 es 
1s J) tik + j - at 
changes oecupred = "i"p? 
locates = i: 
if alobsw then a0 to cn; 
anc, 
substr (tlin, ij-e lergtn 
$j = yi + lenott Cline) = 93 


Yengtn 


(V4ire) - ™; 


if chanjyesloccursed tnen oye 


i) = 


+ 1) = 


iiox Tuser_loutout, 


line; 


orpki, i ™ 


me 


suoste 


e) 


K 


substr (conmandse 


addr (tlind>, 


, 
joe hrki + 138 


4x Continue seanni 
/x Assume only one 
/x &ssume only one 
/x If token there, 
/*x Change all oceu 
/x Try for another 
/x Skip changina e 
f/x jndexes to strin 
/r 

eki + ff, j = 1)3 


/k copy mart to he 
4x copy 91d line */ 


1))? 
/x locate what 


= 137 

/x copy lime uo to 
brekei + if 
in change */ 
jndexe 


/* put 
fe {mcrement 


/* 


Clines mi 


/*x cooy pest of lin 


/* upite changes */ 
le code); 


(cove, “¥e4 


“FP, "Eprop writina change line"); 


call iox ltreutuchars 
if cote *= 4 then an; 
cal] converr 
ap to finrisn? 
erg? 
anne 
Virnel = ij? 
Vene = sucstr ftling if ij d3 
if mn <= 1 tren an: 
if located = 9 tran des 


count count 


ia 


4x Finished */ 


‘ex Get rid of NL i 


ng edit line. 
change. */ 
Aine changed. 


Process {t. 


rreances. */ 
araqument. */ 
mpty line, */ 


gs */ 


add to beainning of line */ 


added */ 


change */ 
~ 1)% 


s x/ 


e x/ 


“commands” */ 
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* 


x/ 


is to be changed */ 


/ 
x/ 


indicate that you did sameting */ 


395 
396 
397 
398 


399 
AgN 


ow 


agit 
402 
4ag3 
aoa 
40s 
406 
407 
woR 
409 
A10 
4ii 
ai? 
413 
aia 
415 
416 
417 
a1R 
419 
420 
u2t 
422 
423 
42a 
425 
426 
427 
428 
a29 
430 
431 
432 
433 
434 
A3s 
436 
437 
a3A 
439 
440 
aut 
aa? 
Ags 
aaa 
aas 
ads 
au? 
age 
“ag 
aso 
451 
45? 
453 
a5a 


call joa. C€"Mothina chanaed by: 


call resetread? 


nes fF 
call put; 
call get? 
go. to chi? 


PR RRKEREKEK COD KREKKKKKER K/ 


call copv; 
call switch; 
ao to mext? 


toos 


IR KREKKEKKEKEE LOTION RKEEKKEKREK &/ 


call copv; 
linel = 43 
a0 to pinput? 


bottom: 


tid 
LR RRKKKKEKKK DAaCkUD KaRKEKHKK ef 


fa" 


ar 


substr ffrom_lsea, 


backups 1 = indt? 
cali copv; 
call switch; 
indf = i + 1? 
do n =n to 93 
J = index (reverse Csunstr (from seo, 
if J *= 0 then indt = ind# = J; 
else if n = 0 then indt = GF 
else do? 
linel = A; 
n= 1; 
inet, indé# = 03 
eo tn eof; 
end? 
end: 
inet = jndf; 
substr (tolsegr t, ingot) = surstr (from _sea, 1 
do inaf = inst + 1 by 1 to csize? 
Suoster (Cline, jnat = indts 1) = 
if substr (froncuseyr indtfe 1) = isl. 


then ao to tine lena? 


end; 

indf = csize? 
line_end: 

linel = indf = inet; 

es if 


a0 to printir 


SK KEKE KE "FFL OT PanUuASt KEEKRKKRER &/ 


file: cal] copy; 


» commands)} 
/x if not located */ 


/® Na Vine buffer */ 


fk Save oters */ 


/* restore otrs */ 

/*x Note that "n" starts negative, 
indf = 1))- NLD 

f/x First line case */ 

fe went off ton of file */ 


7x line starts ss indt */ 
e inde); 
f/x move jn top 
7x find end of 
indf, 1)}3 


4x move into line */ 


of file x«/ 
line */ 


/x search for end of line */ 


4x Finish copy. */ 
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*/ 


cal] save; 
call clean lun; 
Paturn: 


finisis 


LK REKRREEK KS 
“Saves call coov; 
call save; 
QO TO Next 


a 


SK KEKE RE ANF KKKKKEKEK «x / 


eof: count ceunt = ft; 
call 
call resetreacs 


No tO Next? 


Lae KReKKKKAEK T TE? aL FP WP ERY BP FS zee &/ 

teeny: pracegureas /* 
substr (to _sege indt + le YenathA (line)) = line? 

f/x 
indt = inot + length (line)? 
linel = 9; fx 
if csize = vu 
then peturn; /K 
ij = csize = incf, / 
if if > 4 
then sunste fto_ses, inst + 1 i1) = substr (Cfromlsea, 
inet = inet + i)? /* 
incef = csize?r 
return? 
end cove 


igal C#Ene of File 


+ 
/% 
7x 


VPITA Save AEKKKR KEKE OF 


se 
fx 
fx 


sx 


reached bys*/*3a"%, commands); 


Save jt. */ 
Terminate source and release temp segs *x/ 
Return to command precessor */ 


Finish copy. */ 
Save jt. */ 


Continue accepting requests, */ 


Remove NL «/ 


coov rest of file into to file */ 


Copy current line, */ 
No more line */ 


If new input, then no copy needed, */ 


do rest of file */ 


jndf + 1, i13)3 
set coupters */ 


Save? eraceqgure; /*x Procecure to write out all om part of "to" buffer, */ 
if sourceletr = mull then cot /x Must be a new segment x*/ 
call hes ltraxe_ses fuirunares, entry_nater "", O1010bs source _otry, code)} 
if ecde *= % then ur; 
call comerrl fcoue, RYLE«F,. "Cannot create “*a™, pathname, (dirname, entry name))? 
Pefurn3 
end? 
Ons 
substr (source sear !, inmauts = Susstr (tolseas, ir indt); 
call hes_asetuhcusec (sourtercetr, inet * 9 coded; 


if code = 4 
then call 


if code “= U then do 
call comlerry 
inet x Se, 
One? 
returns 
ena sayer 


hes _ttruncate sea (source lote, 


Ceoder “VANES 
Patrmame. Cuoirlname, 


re tao 


divide Cindgt + 3, 


"Cannot truncate/set bit 
ertry name) )3 


Ke 19s O)+ code); 


coumt (“d) on “a, 
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515 
516 
517 
518 
519 
520 
521 
S22 
523 
524 
525 
526 
527 
528 
529 
530 
531 
532 
533 
534 
535 
536 
537 
53R 
539 
540 
541 
542 
543 
54a 
645 
546 
547 
548 
549 
550 
551 
552 
553 
554 
555 
556 
557 
558 
559 
560 
561 
562 
563 
564 
565 
566 
567 
568 
569 
570 
571 
S72 
573 
574 


Put: 
procecure? 
substrp (to_sesg, indt + ir lTerath (line)) 
indt = imdt + length (line); 
Tjrnel = 4; 
Petusn? 
end? 
aets 
procedure; 
linel = 0; 
if indf >= csize then s0 to ecf; 
linel = index Csubstr ffromlsea, indf + 
if linel = 0 then linel = csize = indfs 
line = substr (fromisea, jindf + ly linel); 
tindf = linel + indf; 
Petupn: 
end? 
switch: 
procedure? 
exptr = fromoctr? 
fromuptr = torte; 
to ptr = exptr? 
esize = indt? 
jndts indf = OF 
Time) = 07 
rPetuPpns 


end switch; 


resetreads 
procedure? 
call 


fox Sconmtrol Cioxlsserlinpute 


"resetread", 


fx Call 


x/ 


Reset current line lenath,. 


/* 


next new line. 


Return the line to caller, 
pointer ahead one line. 


line; /* do move x/ 
/* set counters */ 
/x Discard old line. 
/*k 

csize + jndf), NL) 
/* Find the 
7x If no nl founds 
/* 
fe Move the "from® 
/* 


make fron=file to file, 


x/ 


*/ 


*/ 


and vevVe 


xf 


i7o system reset read entry. 


If no tnout left, 


xf 


aive UP, 


treat end of aegment as one, 


x/ 


7x In ane place to centralize error handling */ 


null (€), 


code)? 


/*x Set fop easv failure */ 


/*x Only whitesoace left */ 


$f code *= 0 then call ceomuerr. (code, MYNANE, 
return? 
end resetread? 
cet tokens 
procedure? 
declare ftoken llth» whitellth) fixed oinary (21)? 
tka = "7 8; 
white_Ith = verify (substr (commands, edet), WHITESPACE) = 13 
if whitellth < G then return? 
edet = edet + whitelith; 
tokenllth = search (substr (Cecommandss edet), AHITESPACE) = 13 


if token llth < 0 then tokenlith = 


tim = substr (Ccommandse ecctr token llth)? 
edet = edct + token ith; 
return? 


end get token? 


length (eommandsy= edets - 


/x Extract token */ 


"Cannot resetread userlinput™); 
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*/ 


i7é procedure? 7x Routine to convert token te sinary integer, */ 
7? call gat utoxen? /x Delimjt the token, */ 

‘78 evonune 

79 antry? 7x Enter here if token already avajlable, */ 
‘8A nm o= evodec. (tkni; /x Convert tt. */ 

‘Bt if n= G them n = 4; /x MNefault count is 1. */ 

a? rPeaturn? 

§2 

64 ena get lau? 

Bs 

S4 cleancup? 

e7 procedure? 

ae 

§2 caj! release _termv_seaments. CMr ame, tenp_segs, (9));7 

gn if sourceletr *2 nul] then cali hes _aterminate noname (sourcelotrs, (0))? 

91 

92 eng cleanlun 

Gt 

94 ena eds? 
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SOURCE FILFS USE? TN THIS CUMPTILATIUN, 


LINE NUMBER SATE MODIFTED A OAR PATHNAME 
0 06/01/51 1643.1 ecs.oit >uda>Pubs>userd>AG90=02>eds,011 
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NAMES PECLARFD IN THIS CORPILATION. 


IDENTIFIER OFFSET LOC STUPAGE CLASS 


NAMES DECLARFO BY PECLARE STATEMENT, 


MYNAME 00690 constant 
NL 004102 constant 
WHITESPACE 909091 constant 
addr 
ara.count 906100 automatic 
break N0010C1 automatic 
brkt 909402 automatic 
buffer Q0691°3 automatic 
“hanges_occurred 909170 automatic 
yvanup 900472 stack reference 
Je C0171 automatic 
comlerre 009616 constant 
commands bases 
count 900172 automatic 
esize 909173 automatic 
cucSaraccount 900012 constant 
cu,S$aracoter 909614 constant 
evudec_ 909016 constant 
dirname 909175 automatic 
divide 
edct 009174 automatic 
entry uname 00°247 automatic 
error_table $noarg 000056 external static 
efror_table_Snoentry 000G60 external static 
error table Stoo _many_args 900062 external static 
expand pathname 000020 censtant 
exote 009260 automatic 
fromuptr 909262 automatic 


CATA TYPE 


char(%) 


char(t) 
char(3) 
puiltin function 


fixed bin€17,9) 
char(1) 

fixeco bin(17,0) 
char(210) 


bittl) 
condition 
fixed bin(3S,09) 


entry 


char 


fixea binf21,0) 


fixes binl21,%) 


entry 
entry 
entry 
char(168&) 


builtin funetion 
fixed bin(17,9) 


char(32) 


fixed bin(35,0) 
fixed bin(35,90) 
fixed pinfZ5,9) 
entry 

oointer 
pointer 


ATTRIBUTES AND REFERENCES 
(x indicates a set context) 


initial unaligned del 60 set ref 104% 113% 113% 119% 
119% 127% 143% 189% 15)% 177% 210% 313% 385% 498% 
507x SS2% 589% 

initial unsligned del 56 ref 249 286 288 427 443 S28 

Initial umaligned deol S8& ref 563 566 

dol 85 ref 174 174 199 199 199 199 207 207 214 217 
218 218 236 238 238 264 272 284 284 295 311 311 
3141 314 314 311 329 334 335 337 338 356 358 358 
363 363 366 368 377 377 379 380 383 383 390 395 
S41 468 478 478 480 S17 517 518 531 563 566 567 
568 

del 9 set ref 102% 108 109 

unaligned del 10 set ref 334* 335 337 

del 11 set ref 333% 335 337 338 356 363 368 

unaligned del 12 set ref 174 174 174 174 199 199 199 
199 207 207 207 207 214 217 218 236 238 272 284 
284 329 334 335 337 338 356 363 368 395 468 563 
S64 567 S68 

unaligned del 13 set ref 351% 354% 373% 381 

del 24 pref 135 

dol 14 set ref 102% 103 104% 108% 109% 110% 112 113% 
118 119% 125% 126 127% 139% 141 143% 149% 150 151% 
174% 176 177% 207% 209 210% 311% 312 313% 383% 384 
38S 496% 497 498% 503% 504 504% S506 S5S07* 551% 552 
5S2x 

external de] 64 ref 104 113 119 127 143 151 177 210 
313 385 498 507 552 

unaligned del 15 set ref 199 199 199 199 214 217 218 
236 238 272 284 284 329% 334 335 337 338 356 363 
368 395% 468% 563 566 567 S68 

dcl 17 set pref 174% 189 199 199 199 199 207% 214 214 
217 218 236 238 272 284 284 326 327% 327 329 329 
334 335 337 338 356 363 368 394% 394 395 395 467% 
467 468 468 563 566 567 568 

del 18 set ref 160% 165% 166 166 248 249 252 254 254 
2546 257 276 278 288 289 440 446 482 484 488 §27 
528 539 Saix 

external] de] 65 ref 102 

external del 66 ref 117 

external del 67 ref 580 

unaligned del 20 set ref 125% 139% 143% 143% 496% 
49B«x 498% SO7Te SO7Te 

del 85 ref 165 S04 504 

dol 19 set ref 181% 236 238 272 273% 273 284 284 333 
334 339% 339 563 545* 565 566 567 568 569% S69 

unaligned de? 21 set ref 125% 139% 1O3e 143% 162% 
A96*x 498% AGBx SO7Tx S07 

del 91 ref 109 

del 92 ref 141 

dct $3 ref i116 

external de] 68 ref 125 

dol 22 set ref 538* 540 

de! 23 set ref 155* 166 249 254 264 265 284 286 288 
291 295 427 438 444 443 485 528 531 538 539% 
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framisey 


aetiterrcsegmentse 
alobew 
hes_finitiate_leount 
hes _fmake sec 

hes _fsetlte_ser 
hesu*terminate nonatea 
hes truncate_sen 


inet 


joat 
jioxl*cantral 

for _* set line 
fox ltoutlchkars 
foxltuserlinnut 
fox _tuserloutecnt 


] 


1 
lerotn 
line 


line ltuffer 


linel 


located * 


mul) 
nathrare 


releaseltemp segrents 


reverse 
search 


CONYUR?e 
9OfeFa 
909074 
ACOGZ 
AENYTG 
NENG? 
969034 
NYURERS 


9ON2b6 


NON24; 


904¢74u 


OOP US 
fotgayg 
aoncag 
a09044 
969054 
eanysSe 
MUTT 


O%ET7.¢ 


reneTa 


NO%e7u 


NUNS6] 


AGOS4E? 


LONSRY 


10%3464 


CUNCIE 
fyuPuss 


bases 


constant 
automatic 
constant 
constant 
constant 
constant 
constant 
automatic 


automatic 


automatic 


autonatic 


constant 
constant 
canstant 
constan*® 
external 
external 
automatic 


autoratic 


automatic 


pases 


automatic 


autonatic 


automatic 


automatic 


autematic 


constant 
constant 


Static 
Static 


char(1048576) 


entry 
bitt1) 
entry 
entry 
entry 
entry 
entry 


fixed bin(2t,0) 
fixeg oin(f21,0) 


suiltin funetion 
fixed bin(21,9) 


fixed bint21,9) 


entry 

entry 

entry 

entry 

oointer 

cointer 

tixed bin(21,9) 


fixed bin(21,9) 


fixed binfel,0) 


oviltin funetion 


char 


char(2i0) 


fixed pint17,0) 


fixeo bin(17,0) 


fixed bin(21,0) 


tixed pinl2t,9) 


builtin funetion 
entry 
entry 
builtin function 
builtin funetior 


unaligned del 24 set ref 166% 249 254 264 265 284 
286 288 291 295 427 438 441 443 485 528 5314 

externa] del 69 ref 149 

unaligned del 26 set ref 340% 345% 375 

external del 70 ref 139 

external del 72 ref 496 

external de} 74 ref 503 

external del 75 ref 590 

external del 76 ref 504 

del 27 set ref 226% 247% 284% 285 286 287 335% 336 
337 338 339 353 356 363 368 370 422% 425 ~- 

del 28 set ref 352% 359% 366 368 371% 371 377 379% 
379 389 390 484% 485 485 485 487 

del 85 ref 249 284 286 288 335 337 363 427 528 

del 29 set ref 160% 245 252 256% 262% 265 265 267 
275 276 284 286 287 289% 290% 293 825% 427 428% 
429 429% 433% 437 440% 441 G4, 443% Gdbxe 447 484 
485 48Rx S27 528 528 530 531 S32%x 532 Sd2x 

dcl 30 set ref 160* 254 257% 257 265 267% 267 274 
291 294% 294 422 433% 437* 438 456 440 441 447 4768 
480% 480 485 GA7x 487 S02 S02 503 504 504 S07 517 
Stax 518 $41 Sae* 

external del 77 ref 162 172 199 205 307 329 395 468 

external del 78 ref 551 

#xternal del 79 ref 174 207 

external del 86 ref 311 383 

del 90 set ref 174% 207% SS51i* 

del 90 set ref 311* 383* 

del 31 set ref 245% 248 249 249 260% 260 262 264 
274% 280 280 2A2*% 28Ax 289 290 337% 338 338% 339 
356 356 358 359 360 368 368 371 372 427% 428 428 

del 32 set ref 249% 251 260 263 264 286% 287 287 
287 2868 288 299 291 291 293 294 295 363% 365 366 
366 368 370 371 372 

del 33 set ref 352% 360% 372% 372 380% 380 383% 

deol 85 pef 174 174 199 199 207 207 217 236 272 284 
S41 341 338 358 377 379 389 478 480 517 S18 567 

unaligned del 34 set ref 218% 238% 264% 295% 311 311 
Sit 311 358 358 363 366 377 377 379 380 390% gaye 
478 478 480 517 517 518 53ix* 

uneligned del 35 set ref 218 238 264 295 311 311 314 
311i 358 358 363 3646 377 377 379 360 399 44% 478 
478 480 517 517 518 5314 

del 36 set. ref 217% 218 229% 236% 238 253% 263% 264 
264 265 265 267 293% 295 295 3066 311 311 311 311 
349 358 358 359 360 363 366 377 377 379 380 389% 
390 417% USix 441 447% 478 478 480 481% S17 517 
518 519% 526% S28%x 530 530* 531 531 532 Sa3x 

del 37 set ref 325% 355% 374% 393 

dol 386 set ref 245% 254 254 254 257 265 265 265 267 
275% 282% 291 291 291 294 352% 363 366 370% 370 
377 377 379 360 

del 39 set ref 226 244 287 276% 278 280% 281% 288 
296% 317% 317 318 34ix 392 4Oix AOL A26x% 426m 429 
432% 4O9x% 580% 581 581% 

del 95 ref 133 134 141 161 495 551 551 590 

external del 61 ref 143 143 498 498 507 S07 

external del 82 ref 589 

dct 85 pef 286 427 

dcl 85 ref $66 
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sneme 
ename lth (09345 
snamecptr 9003566 
source count 060370 
source ptr 069372 
source seg 
subste 
temp_secs 809374 
tkn NONGAG 
tlin noONgAG 
toletr - 900479 
tov.seg 
token ith 060556 
rverjfy 
white clth NQOSS7 
MES DECLARED BY FXPLICTT COWTEXT, 
ackup 102uTa 
vad syntax 901775 
sottom 002471 
thi NOP1%6 
the 902293 
thange CO1771 
Sleanlup 903433 
sOPy 80?650 
pet Ng234s 
'V.nuUM O03466 
lellin 601341 
ids HON2%G 
of 00276?1 
‘jle NG?697 
inish 102611 
let 03172 
etunum ON034NZ 
etutoken 003324 
nput 901251 
nsert 001357 
inerend 1902694 
ocate 90152] 
eof N01G3e 
exlin 901373 
ext 901020 
oline 901762 
xarq POPLL4 
edit 901095 
inet O012%o 
pint 9901673 
rinti AOt712 
ut 903157 
esetread NdV%2AD 


pased 

automatic 
automatic 
automatic 
automatic 


oaseg 


automatic 
autonatic 


automatic 
automatic 
pasea 

automatic 


automatic 


constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 


constant 
constant 
constant 
constant 
constant 
constant 
constant 
constant 


char 


fixed bin(21,9) 


pointer 


fixed pin(24,0) 


eointer 


char (1048576) 


puiltin function 


peinter 
char(&) 


chae(?19) 
pointer 


char (10485746) 


fixed pbin(21,9) 
builtin funetion 
fixed binf21,0) 


label 
Tacel 
aoe] 
labe}) 
Jabel 
labe] 
entry 
entry 
lape] 
ertpry 
lapel 
entry 
lapel 
label 
Japel 
entry 
entry 
entry 
laoel 
lave] 
Jahel 
label 
Jabel 
lape] 
label 


label} 
lane] 
lapel 
label 
lave} 
label 
entry 
entry 


unaligned del 40 set ref 125% 127% 

del 41 set ref 117% 125 125 127 127 

del 42 set ref 117% 125 127 

del 43 set ref 139% 165 

del 44 set ref 133% 139% 141 161 166 495 496% 502 
S03% SO4x 590 S90x 

unaligned del 45 set ref 166 S02 

dcl 85 set pref 166% 166 199 199 214 238 249 254% 254 
264 265* 265 284 284 286 288 291% 291 295 334 335 
337 356% 356 358% 363 363 366% 366 368% 368 377 
377 390 427 438% 438 441% 441 443 A78x UBSx 485 
502% 502 S17* 528 531 563 564 568 

array deol 47 set ref 134% 149% 155 156 S89x% 

unaligned de! 49 set ref 184 185 186 187 188 189 190 
191 192 193 194 195 344 345 S62n S68 580% 

unaligned de! 48 set pref 356% 358% 366% 36Ae 377% 
38% 383 390 

del Se set ref 156% 254 265 291 438 478 48S S02 S17 
539 540% 

unaligned deol SO set ref 254% 265% 291% A3ZBx 478% 
485% 502 517* 

del S69 set ref 566% 567 567% 568 569 

det 85 ref 543 

del 560 set ref 563% 564 565 


dct 42? pef 24a 

del 327 ref 272 336 

dct 416 ref 194 

dc? 351 ref 4094 

del 363 ref 375 

det 325 ref 190 

internal de} S86 ref 135 152 456 
internal del 477 pef 299 410 416 423 454 461 
dc! 381 ref 361 

internal de] 578 ref 346 

dc) 224 ref 194 

externa] del] 1 

del 467 ref 252 258 434 527 

del 454 pref 189 

dol 4546 ref 178 211 314 386 
internal del 524 ref 227 320 403 
{nternal del S75 ref 224 243 305 
internal de] 557 ref 182 342 577 
del 207 ref 219 

del 234 ref 184 

deol 447 ref 443 

del 272 ref 186 

det 252 pef 248 

del 243 ref 168 

del 174 ref 180 201 230 239 268 301 318 331 399 412 


del 317 ref 308 

del 342 pref 347 

del 172 raf 214 

dcl 205 ref 163 195 418 

Ac) 305 ref 187 

del 311 ref 297 321 450 

internal del 515 ref 216 234 246 277 319 402 
internal del 548 pref 200 330 397 469 
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retyre NG1346 constant labe] del 236 ref 185 


save C£927%6 constant entry internal del 494 ref 455 462 
skipeh NOP S22 constant labe] del 392 ref 349 

switen AO%E75 constant entry internal del S36 pref 279 300 411 42 
ton NQAAKR, ennstant labe] dcl 410 ref 193 

wsave "972616 constant lave] dcl 461 set ref 192 


THERE WEPR ONT NAMES PECLARED BY CUMTEKT TR [MPL ICATION, 


STORAGE PESUTRE dRaTs FOX THIS PRALRE, 


Sytect Tert ani Symoot Yefs Static 
Start y 0 Gseg Aus "103 4374 
Length en 7a apes aa ely cA 0 
PLICK MATE STACK STZF TYPE MY NONQUICK/WHO SHARES STACK FRAME 
eds Su? external procedure is an external procedure. 
on unit or fine 135% b4 an unit 
copy internal crocedure shares stack frame of external procedure eds, 
save internai oroceture shares stack frame of external procedure eds, 
put internal orocedure shares stack frame of external procedure eds. 
aet internaji crocedure shares stack frame of external procedure eds, 
switch intesnal prcocecure shares stack frame of external procedure eds. 
resetread internal procedure snares stack frame of external procedure eds, 
set itoker internal orocedure shares stack frame of external procedure eds. 
gqefonum internaj proceture shares stask frame of external crocedurs eds. 
cleans lus bd internal procecure is called by several nonaquick procedures, 


STORMS FUP AL TUSSTIS uP betes, 


STACY FRALE ge TLELTEPLEX BLOCK NAME 
eds 190TU% aroleount eds 
vegtei break eos 
G2G19? Spy e9s 
2°G41G3 buffer eas 
UADVLTTY rhances_ocrurtren eds 
efut7t code eds 
99617? count eda 
USQ1TS esize eds 
QOyi7h edet eds 
“UFG1TTS dir_lrame eas 
u%Q2G7 antrpyonate eds 
vy?6® exete ess 
U%GP%H? Fpanopter eqs 
VR QPot elabse eds 
uMFeS F ads 
AYP. Fy eas 
U%D?P ET Iindf 20s 
Q%779 Inst eds 
OAge71 | eds 
QN9n777 & eas 
w9agr7k Y eds 
290975 line_buftfer eos 
0°0%301 line} eds 
G20%6? located aos 
399362 eds 
yAg%64d on eds 
Q°G%6S sname_Tth eds 
C% 3045 snamecetr eds 
099779 source rcount eds 


000372 sourcecptr 


000374 temp_segs 
99040° tlin 
000466 tn 
O20487% tolptr 
GO00556 token ith 
O905S7 white th 


THE FOLLOWING FXTEPNAL UPEPATORPS APE USED Ry THIS PROG? AM, 


allocics calllextlout dese cal] text lout 
enable Shorten_stack extcentry 


THE FOLLOWING FXTEPNAL ENTPIES ARE CALLED 2Y THIS PRNG@A, 
comlerr,, cCulwaralcount 


exoand pathname. 

hes Sset be sea 
fox.Scontrol 
release_temp_segrents_ 


get_temp_segmants_ 
hos_Sterminate_noname 
jor _fgetlline 


THE FOLLOWING FXTEPNAL VARTABLFS APE USED RY THIS PROGRAM, 


error_tablea_Snoarg 
fox Suserloutput 


LINE LOC LIME Loc LIWE 
1 900227 1%2 090235 103 
110 009390 1i2 0°930% 113% 
120 009414 125 of0442 124 
135 000514 139 000534 tq 
151 900796 1%2 00073? 15% 
162 000752 1463 090775 165 
177 901045 478 004074 1a% 
186 001115 1R7 09112? 188 
193 0011690 1°4 001165 1$5 
207 001251 209 oNypza P14 
218 601335 219 091349 Pei 
230 901355 274 01357 254 
245 901376 246 001403 247 
253 (01435 254 091436 254 
26? 401444 263 004464 P64 
273 901524 274 691525 275 
280 901542 21 091547 282 
26R 001613 229 001427 9% 
296 001065 2°7 09146607 299 
307 901676 306 001711 34 
318 001764 319 091764 320 
329 991777 330 692025 231 
337 002056 338 002076 339 
345 007172 346 002132 247 
354 002146 355 992159 354 
36% 002293 345 002227 366 
373 002394 374 002206 275 
283 A02347 3°4 692364 385 
39% 800425 394 002427 395 
#02 002464 and O92K465 ayn 
ALR CO2473 422 ONeA7a4 423 
428 002524 429 0025340 A314 
437 102544 47S G0e544 S40 


error utablelsnoenrtry 


LAS 
VAN24S 
2G9395 
90g! 
HOR OOG 
ngny%e 
SulTT7a 
90TG75 
401127 
AG1L72 
C9127%5 
AO154) 
001560 
oglane 
aulgss 
aut47y 
9015?7 
01550 
901073 
AOL67E 
ev17Tte 
A01747 
102076 
0G?2154 
002133 
N074S¢ 
S02 E36 
a0es19 
N02357y 
OG24u%4 
N02 46d 
NG2u76 
GG253%4 
902554 


LINE. 


114 
1°7 
143 
155 


eqs 
eds 
eas 
eds 
eds 
cet token 
aet token 


calllint wth 
intlcentry 


euLSaroleter 


is 


calllintlother 
set csleis 


heslfinitiate count 
Aes_*truncate sea 


fox _fputuch 


error_table Stoo many args 


Loc 
ONg?24y7 
GOG334 
ongaga 
0o0A19 
090737 
091001 
oO1109 
901134 
081177 
091%¢? 
00134? 
001362 
ye14it 
001455 
QO1477 
991531 
094552 
091635 


» ONLATI 


Q9173% 
991779 
v02027 
oo2iit 
one134 
u02166 
092266 
002212 
o%2ajia 
092457 
G92k67 
092477 
602535 
042563 


ars 


LINE 
105 
117 
128 
144 
156 
172 
182 
196 
290 
aia 
227 
239 
249 
258 
267 
277 
285 
293 
301 
313 
325 
334 
344 
351 
359 
370 
379 
389 
399 
412 
425 
433 
A43 


LAC 
900264 
900335 
000476 
909662 
000741 
001095 
001102 
001141 
901233 
001303 
901352 
001372 
o0Lai4 
601460 
001514 
001534 
001571 
001651 
001672 
001735 
001771 
002032 
002112 
002136 
902173 
002265 
002335 
902415 
992460 
002470 
007599 
002537 
002571 


eve 
hes_Smake_seg 


dec. 


loa, 


Pathname. 


fox Suser_linput 


LINE 
108 
118 
133 
149 
160 
174 
184 
191 
201 
216 
228 
243 
251 
260 
268 
278 
286 
294 
305 
314 
326 
335 
342 
3$2 
360 
371 
380 
390 
any 
416 
426 
434 
44s 


Loc 
000265 
000355 
000477 
060663 
O00743 
o0102n 
001103 
001146 
001235 
001332 
001353 
001373 
001431 
001461 
001520 
001535 
091572 
001654 
001673 
QO1761 
091772 
002937 
002114 
002137 
002177 
002272 
092341 
002417 
002461 
on2a71 
002503 
002541 
902575 
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return 
index es leis 


LINE 
109 
119 
134 
150 
161 
176 
185 
192 
205 
217 
229 
244 
252 
261 
272 
279 
287 
295 
306 
317 
327 
336 
344 
353 
361 
372 
384 
392 
4Q2 
417 
427 
436 
446 


LOC 
009272 
000357 
000501 
OONTO4 
009746 
601043 
901110 
001153 
001236 
001333 
001355 
001374 
001432 
001462 
001521 
001541 
0016%6 
101660 
001674 
901762 
001775 
002055 
00F115 
002143 
002202 
002277 
002345 
002422 
002463 
CO2472 
002807 
002542 
002577 


ay? 
461 
o77 
487 
aga 
E14 
526 
536 
Saf 
Sot 
BTN 
S66 


AYPGOY 
Q>616 
CO268G 
No2701 
NG2TSY 
AO31LS6 
0034173 
693295 
ken Fen sin | 
VG %3°7 
AUBGNG 
ORa%2 


ON246)4 


2 ON2A)7 


092651 
UOeTOS 


3 99307 


03157 
OO517A 
993226 
0°35? 42 
UNZZAA 


3 UMZees 


grgauen 


9G? aM 
99? 02% 
NYP oS7 
NyP?T95 
2U30%U 
Ngai ey 
U3i77 
usZ3u 
ngreas 
993352 
994 4%% 
nytaere 


002607 
00242) 
o9eb6o1 
on2706 
005036 
093166 
gng21a 
gng23e 
003275 
903353 
g93495 
693501 


45s 
468 
482 
ags 
504 
519 
531 
S41 
553 
507 
589 


902610 
002623 
902662 
002797 
003054 
003170 
003220 
003234 
103323 
003372 
003407 


456 
469 
484 
496 
506 
520 
532 
542 
557 
568 
SA1 


002611 
002646 
092665 
092713 
003075 
903171 
003223 
003236 
003324 
003376 
003426 
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457 
470 
485 
497 
507 
52a 
533 
543 
562 
569 
582 


002615 
002647 
002667 
002752 
003077 
003172 
003224 
003240 
903325 
003401 
003431 


APPENDIX C 


MULTICS SUBSYSTEMS 


The Multics system offers many special ‘subsystems, designed to serve a 
particular set of users or perform a particular set of tasks. Some of these 
subsystems are already familiar to you--the Qedx and Emacs text editor systems, 
the input/output system. Various other subsystems are described briefly here. 
For detailed information on any of them, see individual manuals. 


DATA BASE MANAGER 


The Multies Data Base Manager (MDBM) supports the description and processing 
of data bases of widely varying sizes and organizations, and provides a large 
measure of data independence. It consists of an integrated set of functions 
which offer a full range of data base retrieval and update capabilities, and it 
is written to interface with any programming language that supports a call statement. 
The MDBM offers a powerful, extremely flexible method of structuring and manipulating 
data bases: the Multics Relational Data Store (MRDS). 


MRDS supports the relational model of data base organization, in which data 
relationships are represented by means of formal algebraic entities. It allows 
you to structure and access data without concern for how or where it is actually 
stored. A special MDBM query language called LINUS (described later in this 
section) provides comprehensive query capabilities for MRDS data base users. 


Data bases reside within the Multics storage system and are protected by 
all of the security features inherent in the Multics virtual memory environment. 


FAST 


The Multics FAST subsystem is a simple-to-use, low-cost user interface for 
creating and running BASIC and FORTRAN programs. The Multics FAST command language 
is a subset of Multiecs commands with additional commands for manipulating 
line-numbered text. 


GCOS ENVIRONMENT SIMULATOR 


The GCOS environment simulator, together with several Multics facilities, 
permits GCOS batch-processing jobs to be run under the control of Multics and 
provides some job-scheduling facilities. Invoked via the Multics gcos command, 
the simulator immediately runs one GCOS job in your process. Your terminal is 
treated as if it were the GCOS operator's console. 
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It's also possible to simulate GCOS time-sharing usage, by invoking the 
Multics geos_tss (gtss) command. 


GRAPHICS 


The Multiecs Graphics System provides a general purpose interface through 
which user or application programs can create, edit, store, display, and animate 
graphic material. It is a terminal-independent system, which means that a program 
written for one type of graphic terminal is operable without modification on 
another terminal having similar capabilities. 


The Logical Inquiry and Update System (LINUS) is a facility for accessing 
MRDS data bases. The complete data base management capability provided by LINUS 
includes both retrieval and update operations. 


LINUS makes use of a high-level nonprocedural language called LILA (LINUS 
Language) that can be understood by individuals who aren't necessarily computer 
specialists. 


REPORT PROGRAM GENERATOR 


The Multics Report Program Generator (MRPG) is a language translator used 
to generate a PL/I source program from an MRPG source program, with the purpose 
of generating formatted reports. 


SORT/MERGE 


The Sort/Merge subsystem provides generalized file sorting and merging 
capabilities, specialized for execution by user-supplied parameters. Sort orders 
an unranked file according to the values of one or more specified key fields in 
the records you are using. Merge collates the contents of up to ten ordered 
files according to the value of one or more key fields. Input and output files 
associated with the Sort/Merge subsystem can have any file organization and be 
on any storage medium. Records can be either fixed or variable length. 


WORDPRO 


The Multics word processing system, WORDPRO, consists of a set of commands 
that assist you in the input, update, and maintenance of documents. The commands 
provide tools for text editing and formatting, Speedtype, dictionaries for 
hyphenation and spelling, list processing, and electronic mail. 


An important part of the WORDPRO system is the compose command, which is 
used for formatting manuscripts, and has programmable requests that make it a 
minor programming language. 
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APPENDIX D 


THE EDM EDITOR 


The Edm editor is a simple Multics context editor which is used for 
ereating and editing ASCII segments. Edm is less sophisticated than Qedx, and 
far less sophisticated than Emacs, so if you are already comfortable with one of 
these editors, this appendix will not be very useful to you. However, if you 
would like to learn how to use a simpler editor, this appendix will help. 


To invoke the Edm editor, you type: 
edm pathname 


when pathname identifies the segment to be either edited or created. 


The Edm editor operates in one of two principal modes: edit or input. If 
pathname identifies a segment that is already in existence, Edm begins in edit 
mode. If pathname identifies a segment that does not exist, or if pathname is 
not given, Edm begins in input mode. You can change from one mode to the other 
by issuing the mode change character: a period (followed by a carriage return) 
which is the only character on a line. For verification, Edm announces its mode 
by responding "Edit." or "Input." when the mode is entered. 


The Edm requests assume that the segment consists of a series of lines and 
has a conceptual pointer to indicate the current line. (The "top" and "bottom" 
lines of the segment are also meaningful.) Some requests explicitly or 
implicitly cause the pointer to be moved; other requests manipulate the line 
currently pointed to. Most requests are indicated by a single character, 
generally the first letter of the name of the request. 


REQUESTS 


Various Edm requests and their functions are listed below. Detailed 
descriptions of these requests are given later in this section. This list does 
not include all of the Edm requests; it identifies only those requests that you 
will need as you begin using this editor. For a complete listing and 
description of all the Edm requests, see the MPM Commands. 


- backup 


= print current line number 


; comment mode 
° mode change 
b bottom 

d delete 
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f find 


z insert 
k kill 

1 locate 
n next 

p print 

q quit 

r retype 
s substitute 
t top 

Vv verbose 
W write 


GUIDELINES 


The following list offers helpful suggestions about the use of Edm. 


1. 


It is useful to remember that the editor makes all changes on a copy 
of the segment, not on the original. Only when you issue a w (write) 
request does the editor overwrite the original segment with the edited 
version. If you type a gq (quit) without a preceding w, the editor 
warns you that editing will be lost and the original segment will be 
unchanged, and gives you the option of aborting the request. 


You should not issue a QUIT signal (press ATTN, BRK, INTERRUPT, etc.) 
while in the editor unless you are prepared to lose all of the work 
you have done since the last w request. However, if a QUIT signal is 
issued, you may return to Edm request level without losing your work 
by issuing the program_interrupt command. 


If you have a lot of typing or editing to do, it is wisest to 
occasionally issue the w request to ensure that all the work up to 
that time is permanently recorded. Then, if some problem should occur 
(with the system, the telephone line, or the terminal), you only lose 
the work done since your last w request. 


You should be sure that you have switched from input mode to edit mode 
before typing editing requests, including the w and gq requests. If 
you forget, the editing requests are stored in the segment, ins.ead of 
being acted upon. You then have to locate and delete them. 


As you become more familiar with the use of Edm, you may conclude that 
it provides verification responses more often than necessary, thus 
Slowing you down. You may use the k (kill) request to "kill" the 
verification response. However, once you feel confident enough to use 
the k request, you are probably ready to begin using the more 
sophisticated editor, Qedx. The Qedx editor provides you with a 
repertoire of more concise and powerful requests, permitting more 
rapid work. 
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REQUEST DESCRIPTIONS 


The following Edm requests are the ones that you will find most useful as 
you begin working with this editor. Examples are included to help you see the 
practical use of each request. 


Backup (-) Request 


The backup request moves the pointer backward (toward the top of the 
segment) the number of lines specified, and prints the line to show the location 
of the pointer. For example, if the pointer is currently at the bottom line of 
the following: 


get list (nl, 2); 

sum = nl + n2; 

put skip; 

put list ("The sum is:", sum); 


and you want the pointer at the line beginning with the word "sum," you type: 


f -2 
sum = nil + n2; 


If you don't specify a number of lines with the backup request, the pointer 
is moved up one line. (Typing a space between the backup request and the 
integer is optional.) 


SE ES NN | oe 


The print current line number request tells you the number of the line the 
pointer is currently pointing to (all the lines ina segment are implicitly 
numbered by the system--1, 2, 3,..., n). 


Whenever you want to check the implicit line number of the current line, 
you issue this request and Edm responds with a line number. 


143 


Comment Mode (,) Request 


When you invoke the comment mode request, Edm starts printing at the 
current line and continues printing all the lines in the segment in comment mode 
until it reaches the end of the segment, or until you type the mode change 
eharacter (a pericd) as the only entry on a line. 


To print the lines in comment mode means that Edm prints a line without the 
carriage return, switches to input mode, and waits for your comment entry for 
that line. When you give your comment line and a carriage return, Edm repeats 
the process with the next line. 


If you have no comment for a particular line, you type only a carriage 
return and Edm prints the next line in comment mode. When you want to leave 
comment mode and return to edit mode, you type--as your comment--the mode change 
character (a period). 
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Programmers will find that the comment mode request gives them a fast and 
easy way to put comments in their programs. 


Mode Change (.) Request 


The mode change request allows you to go from input mode to edit mode or 
vice versa simply by typing a period as the only character on a line. This 
request is also the means by which you leave the comment mode request and return 
to edit mode. 


For example, when you finish typing information into a segment, you must 
leave input mode and go to edit mode in order to issue the write (w) request and 
save the information. 


! last line of segment 
! 
Edits 
! ow 


Bottom (b) Request 


The bottom request moves the pointer to the end of the segment (actually 
sets the pointer after the last line in the segment) and switches to input mode. 
This request is particularly helpful when you have a lot of information to type 
in input mode; if you see some mistakes in data previously typed, you can switch 
to edit mode, correct the error, then issue the bottom request and continue 
typing your information. 


red 
oramge 
yellow 
green 


Edit. 
! -2 

oramge 
! s/m/n/ 

orange 
! ob 

Input. 
! blue 


Delete (d) Request 


This request deletes the number of lines specified. Deletion begins at the 
current line and continues according to your request. For example, to delete 
the current line plus the next five lines, you type: 


! d6 
If you issue the delete request without specifying a number, only the 


current line is deleted. (That is, you may type either d or d1 to delete the 
current line.) 


After a deletion, the pointer is set to an imaginary line following the 
last deleted line but preceding the next nondeleted line. Thus, a change to 
input mode would take effect before the next nondeleted iine. 
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Find (f) Request 


The find request searches the segment for aline beginning with the 
character string you designate. The search begins at the line following the 
current line and continues, wrapping around the segment from bottom to top, 


until the string is found or until the pointer returns to the current line; 
however, the current line itself is not searched. If the string is not found, 
Edm responds with the following error message: 


Edm: Search failed. 


If the string is found and you are in verbose mode, Edm responds by 
printing the first line it finds that begins with the specified string. 


ae Tae i 
If the string is found and you are in verbose mode, Edm responds by 


When you type the string, you must be careful with the spacing. A single 
space following the find request is not significant; however, further leading 
and embedded spaces are considered part of the specified string and are used in 
the search. 


In the find request, the pointer is either set to the line found in the 
search or remains at the current line if the search fails. Also, if you issue 


the find request without specifying a character string, Edm searches for the 
string requested by the last find or locate (1) request. 


Insert (i) Request 


The insert request allows you to place a new line of information after the 
current line. 


If you invoke the insert request without specifying any new text, a blank 
line is inserted after the current line. If you type text after the insert 
request, you must’ be careful with the spacing. One space following the insert 
request is not significant, but all other leading and embedded spaces become 
part of the text of the new line. 

For example, if the pointer is at the top line of the following: 


sum = nl + n2; 
put list ("The sum is:", sum); 


and you issue the following insert request: 
! i put skip; 
the result is: 
Sum = nl + n2; 


put skip; 
put list ("The sum is:",sum); 


If you want to insert a new line at the beginning of the segment, you first 
issue a top (t) request and then an insert request. 
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Kill (k) Request 


The kill request suppresses the Edm responses following the change (c), 
find (f), locate (1), next (n), and substitute (s) requests. To restore 
responses to these requests, you issue the verbose (v) request. 


It is recommended that as a new user you not use the kill request until you 
are thoroughly familiar with Edm. The responses given in verbose mode are 
helpful; they offer an immediate check for you by allowing you to. see the 
results of your requests. 


Locate (1) Request 


The locate request searches the segment for a line containing a 
user-specified string. The locate and find (f) requests are used in a similar 
manner and follow the same conventions. (Refer to the find request description 
for details.) With the find request, Edm searches for a line beginning with a 
specified String; with the locate request, Edm searches for a line 
containing--anywhere--the specified string. 


Next (n) Request 


The next request moves the pointer toward the bottom of the segment the 
number of lines specified. If you invoke the next request without specifying a 
number, the pointer is moved down one line. When you do specify the number of 
lines you want the pointer to move, the pointer is set to the specified line. 
For example, if you type: 


! n4 


the pointer is set to the fourth line after the current line. The Edm editor 
responds, when in verbose mode, by typing you-specified line. 


Print (p) Request 


The print request prints the number of lines specified, beginning with the 
current line, and sets the pointer to the last printed line. If you do not 
specify a number of lines, only the current line is printed. 


If you want to see the current line and the next three lines, you type: 


! p4 
current line 
first line after current line 
second 
third 


In Edm, every segment has two imaginary null lines, one before the first 
text line and one after the last text line. When you print the entire segment, 
these lines are identified as "No line" and "EOF" respectively. 
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Quit (q) Request 


The quit request is invoked when you want to exit from Edm and return to 
command level. 


For your convenience and protection, Edm prints a warning message if you do 
not issue awrite (w) request to save your latest editing changes before you 
issue the quit request. The message reminds you that your changes will be lost 
and asks if you still wish to quit. 


t 
: q 

Edm: Changes to text since last "w" request will be lost if you quit; 
do you wish to quit? 


If you answer by typing no, you are still in edit mode and can then issue a 
write (w) request to save your work. If you instead answer by typing yes, you 
exit from Edm and return to command level. 


Retype (r) Request 


The retype request replaces the current line with a different line typed by 
you. 


One space between the retype request and the beginning of the new line is 


not significant; any other leading and embedded spaces become part of the new 
line. To replace the current line with a blank line, you type the retype 


request and a carriage return. 


Substitute (s) Request 


The substitute request allows you to change every occurrence of a 
particular character string with a new character string in the number of lines 
you indicate. If you are in verbose mode (in which Edm prints responses to 
certain requests), Edm responds by printing each changed line. If the original 
character string is not found in the lines you asked Edm to. search, Edm 
responds: 


Edm: Substitution failed. 


For example, if the pointer is at the top line of the following: 


get list (n1, n2); 

Sum = nl + n2; 

put skip; 

put list ("The sum is:", sum); 


and you want to search the next three lines and change the word "sum" to 
"total," you type: 


! s4/sum/total/ 


total = n1 + n2; 
put list ("The total is:", total); 
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The four lines searched by the editor are the current line plus the next 
three. (The search always begins at the current line.) If you do not specify 
the number of lines you want searched, Edm only searches the current line. If 
you do not specify an original string, the new string is inserted at the 
beginning of the specified line(s). 


Notice in the example that a slash (/) was used to delimit the strings. 
You may designate as the delimiter any character that does not appear in either 
the original or the new string. 


Top (t) Request 


The top request moves the pointer to an imaginary null line immediately 
above the first text line in the segment. (See the print request description 
concerning imaginary null lines in Edm.) 


An insert (i) request immediately following a top request allows you to put 
a new text line above the "original" first text line of the segment. 


Verbose (v) Request 


dm to print responses to the change (c), find 


stitute (s) requests 


tvuuve vwvees 


co 7 


Actually, you do not need to issue the verbose request to cause Edm to 
print the responses; when you invoke Edm, the verbose request is in effect. The 
only time you need to issue the verbose request is to cancel a previously issued 
kill (k) request. 


Write (w) Request 


The write request saves the most recent copy of a segment in a pathname you 
specify. (The pathname can be either absolute or relative.) 


If you do not specify a pathname, the segment is saved under the name used 
in the invocation of the edm command. When saving an edited segment without 
specifying a pathname, the original segment is overwritten (the previous 
contents are discarded) and the edited segment is saved under the original name. 


If you do not specify a pathname and you did not use a pathname when you 
invoked the edm command, an error message is printed and Edm waits for another 
request. If this happens, you should reissue the write request, specifying a 
pathname. 
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INDEX 


MISCELLANEOUS 


-absentee control argument 7-4 
-all control argument 1-1 

-arguments control argument 7-6 
-brief control argument 1-1 


-brief_table control argument 2-5 


-first control argument 6-3 
-link control argument 2-11 


-list control argument 
1=3 


2-3, 6-3, 6-4, 


-long profile control argument 6-3 
-map control argument 2-4, 2-5, B-2 
-notify control argument 7-4, 7-6 

-optimize control argument B-2 


-profile control argument 


6-1, 6-2, 


-sort control argument 6-3 


-table control argument 2-4, 3-6, 5-6, 
5~8 


absentee facility 1-1, 4-12, 
7-4, 7-5, 7-6, 8-5, 8-9, 
accepting arguments 7-5 
capabilities 7-5 
control file 7-1, 7-3, 7-5, 7-6 
enter abs request command [-1, 


7-3; 


input file 7-1, 7-3, 7-5, 7-6 

job 1-1, 4-12, 7-1, 7-4, 7-5, 7-6, 
8-5, 8-10 

output file 7-1, 7-5, 7-6 

process 1-4, 7-1 


[= 
absin segment 7-1, 7-3, 7-5, 7-6 


production runs 
absolute pathname A-6, B-5 
absout segment 7-1, 7-5, 7-6 


access 1-5, 2-6, 2-8, 4-5, 8-4, 8-1, 
B-5, C-1 
access control list 1-12, 8-4 


ACL 
see access control list 


add search rules command 8-7 


address space 1-2, 1-10, 2-6, 3-1, 
3-5, 8-4, 8-5, 8-8, B-6 
addressing online storage 1-7, 3-2, 
A-1 
add_search paths command 3-7, 8-4, 
add_search rules command 3-3, 8-4 
administrative control 1-12, 3-3 
alignment of variables B-2 
ALM programming language 1-10, 2-1, 
2-2, A-4 
apl command 8-5 
APL programming language 2-1, 2-3, 
8-5, A-1 
archive 
component 2-11, 8-2, 8-6 
segment 2-8, 8-2, 8-6 


archive command 2-8, 2-8, 8-2, 8-6 


4-9, 4-10 


io. dno, 216 


attach description 


attaching switch 


automatic storage 5-5 
B 
background 1-4, 7-1 


backup request 
see Edm editor requests 
basic command 4-10 


BASIC programming language 2-1, 8-5, 
C-1 


batch 7-1 


binary 2-2, 2-5, 2-9, 4-7, B-2 


1-1, 


bind command 2-11, 8-5 
binding 
bind command 2-11 
binder 2-11 


bound segment 2-11 
bit count 1-9, 8-2, 8-3, A-6 


bottom request 
see Edm editor requests 


builtin functions 


divide B-7 
index B-9 
reverse B-9 


search B-10 
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builtin funetions (cont) 
substr B-9 
verify B-10 

bulk data input 4-12 


byte size 1-9 


ecards 
bulk data input 4-12 
control 4-12, 7-3 
conversion 4-12 
input 4-12, 7-3 
remote job entry 4-12, 7-3 
change wdir command 3-2, 8-4 
change wdir_ subroutine 3-2 


character string 3-2, 7-5, A-5, B-2, 
D-5 


cleanup handler B-5, B-6 

close file command 4-10, 8-6 

closing switch 4-4, 4-5, 4-9, 4-10 

eobol command 8-5 

COBOL programming language 2-1, 2-6, 
Baf B28, daes HONG Yar Uap, 
4-11, 5-1, 8-5, 8-10 


cobol_abs command 7-6, 8-5, 8-9 


command 
level 2-6, 3-6, 4-10, 5-1, 5-3, 5-5, 
5-8, 6-1, D-7 
line 2-3, 6-2, 7-6, 8-4, 8-7, 8-8 
name B-5 
processor 5-3, 5-5, 5-7, B-5 


commands 
add search paths 3-7 
add search rules 3-3, 8-4 
apl 8-5 ~ 
archive 2-8, 2-8, 8-2, 8-6 
basic 4-10 
bind 2-11, 8-5 
change wdir 3-2, 8-4 
close file 4-10, 8-6 
ecobol 8-5 
cobol abs 7-6, 8-5, 8-9 
compare ascii 2-7, 8-2 
compose 8-2, 8-5, C-2 
copy 2-7, 8-2 
copy cards 4-11, 4-12 
copy file 4-11, 8-2, 8- 
create data segment 8-5 
delete search paths 8-7 
delete search paths 3-7, 
delete search rules 3-3, 
discard output 6-2, 8-7 
display pllio error 4-1 
edm 8-2, D-1, D-8 
enter abs request 7-1, 7-3, 7-4, 

7-6, 8-10 

exec com 2-8, 7-5, 7-6, 8-7 
fast 8-5, 8-7 
file output 4-11, 8-7 
format_cobol_ source 2-7, 8-5 
fortran 7-3, 8-5 
fortran abs 7-6, 8-5, 8-10 
geos 8-8, C-1 
geos tss C-1 
general ready 2-8, 8-6, 8-8 
get system search rules 8-4, 8-8 
indent 2-7, 8-2 — 
initiate 3-2, 3-5, 8-4 
io call 4-2, U-u, 4-5, 


av woes 


4-10, 8-7 


“3 . PMs 


commands (cont) 
Link 2-11, 353; B-2,.-829 
Vist. 2241, 84, 853 
list external variables A-3 
list ref_names 3-5, 8-4 
move 2-7, 8-3 


new proc 1-4, 3-5, H-2, 8-4 

pll O24) 2u5,. 228, 259. 2290,2 5-4" 
5-6, 6-1, 8-5 

pli abs 7-6, 8-5 

print 2-4, 4-11, 5-6, 7-4, 7-5, 7-6, 
8-4, 8-5, 8-6, 8-7 

print attach table 4-11, 8-7 

print search paths 3-7, 8-4, 8-8 

print search rules 3-2, 8-4, 8-8 

eee acts 5-1, 5-5, 5-6, 5-8, 5-7, 

profile 6-1, 6-2, 6-3, 8-6, B-9 

program interrupt 2-7, 8-8, D-2 

progress 2-5, 8-6, 8-10 

release 2-7, 5-3, 5-5, 5-8, 8-8, 


Be-5 
rename 2-7, 8-3 
resolve linkage error 3-7, 8-8 
revert output 4-11 
set_search paths 3-7, 8-4, 8-8 
set_search rules 3-3, 8-4, 8-8 
start 2-5, 2-7, 3-7, 5-3, 5-5, 
status 8-3 
stop cobol run 4-1 
terminal output 4- 
terminate 3-5, 8-4, A-2 
terminate refname 3-5 
terminate segno 3-5 
terminate single refname 3-5 
trace 5-1, 5-8, 8-6 
trace stack 5-5, 8-6 
unlink 2-11, 8-3 
where search paths 3-7, 8-5, 8-8 


who 7-4, 8-10 


comment mode request 
see Edm editor requests 


compare ascii command 2-7, 8-2 


compiler 1-10, 1-12, 2-3, 2-4, 2-5, 
2-6, 2-10, 6-1, 8-5, 8-6, 8-10, 
B-1, B-2, B-4, B-3 


compiling 1-1, 2-6, 3-5 
compose command 8-2, 8-5, C-2 
com_err_ B-5 


com_err_ subroutine A-5, A-6, B-4, 


B-5, B-6 
constant 2-5, B-3 


control arguments 
-absentee 7-4 
-all 1-1 
-arguments 7-6 
-brief 1-1 
-brief table 2-5 
-first 6-3 
-link 2-11 
-list 2-3, 6-3, 7-3 
-long profile 6-3 
-map 2-3, 2-4, 2-5, B-2 
-notify 7-4, 7-6 
-optimize B-2 
-profile 6-1, 6-2 
-sort 6-3 
-table 2-4, 3-6, 5-6, 5-8 


control cards 4-12, 7-3 
control characters B-3 


controlled security 1-1, 1-12, 2-1, 
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controlled sharing 
1-10, 1-12, 


ie he 
22145. B=3 


1-5, 


copy command 2-7, 8-2 
copy_cards command 4-11, 4-12, 8-6 
copy file command 4-11, 8-2, 8-6 


core 
see memory 


core image i-2 

create data segment command 8-5, A-4, 
Az 

create data segment _ subroutine A-4, 
A-5 


cu_ subroutine B-4 
cu_$arg count B-4 


cu_$arg_count subroutine B-4 


eu_$arg ptr B-5 
cu_$arg_ ptr subroutine B-5 
ev_dec_ subroutine B-4, B-10 


daemon 1-4, 8-3, 8-5, 8-9 


data base manager subsystem C-1 


debugging 1-1, 2-2, 2-3, 2-4, 2-6, 
3-5, 5-1, 5-5, 5-6, 5-8, 6-1, T-1, 
8-6 
debugging tools 
see probe 
default 2-3, 4-2, 4-4, 4-5, 4-9, 5-6, 
8-4, 8-7, 8-8, A-2, B-2 
definition section 2-5 
delete request 
see Edm editor requests 
delete search paths command 3-7, 8-4, 
8-7 
delete search rules command 3-3, 8-4, 


8-7 
designing 2-1 
detaching switch 4-2, 4-5, 4-10 
device independence 4-1 
direct intersegment references A-3 


directory 2-3, 2-4, 2-11, 3-2, 3-3, 
7-1 9 8-3, 8-4, 8-7, 8-8, 8-9, A-6, 


B-4, B-5 
home 3-2, 7-1 
working 2-3, 2-4, 2-11, 3-2, 3-3, 


4-8, 8-4, 8-7, 8-8 
diseard output command 6-2, 8-7 


display plilio_error command 4-11, 8-6, 


divide builtin function B-7 


documenting 2-1, 2-7 


dollar sign 3-2, A-4, B-4 


dynamic linking i-1, 
3-5, 3-7; A-4 


1aiO;. Pass. 3-4; 


usage 3-5 
E 
editing 1-10, 2-2, 2-5, 8-2, B-3, C-2, 
D-2 
editor 2-2, 2-8, 3-6, H-4, 7-4, B-3, 
B-5, D=1 
Edm 2-2, 8-2, B-1, D-1 
Emacs 2-2, 8-2 
Qedx 2-2, 2-8, 2-9, 2-10, 3-1, 3-6, 
7-4, 8-2 
Ted 2-2, 8-2 


edm command 8-2, B-1, D-1, D-8 
Edm editor 2 
requests D 
backup D- 
bottom D 
comment m 
delete D 
find D-5 
insert D-5 
kill D-6 
locate D-6 
mode change 
next D-6 
print D-6 
print current line number 
quit D-7 
retype D-7 
substitute 
top D-8 
verbose 
write 


D-4 


D~3 


D-7 


D-8 
D-8 


Emacs editor 2-2, 8-2 


enter_abs request command 


- - -1 


? ? 


1-10, 3-2, 3-6, 5-6, A-5, 


T-i, 7-3, 


entry point 


? 


entryname 2-2, 2-3, 2-6, 8-5, 8-8, 
A-6 
error handLing 1-4, 1-10, 2-5, 2-6, 
2-7, 3-5, 3-6, 3-7, 4-5, 4-11, 
5-5, 5-6, 5-7, 8-6, 8-8, A-5, A-6, 
B-2, B-3, B-4, B-5, D-4, D-5, D-8 
error output switch 4-5, 4-11 
execution 1-2, 1-4, 1-10, 2-1, 2-3, 
2-5, 2-6, 4-12, 5-2, 5-3, 5-6, 
6-3, 7-1, 7-3, 8-5, 8-6, 8-7, 8-8, 
A-4 
execution point 1-4 
exec com command 2-8, 7-5, 7-6, 8-7 
expand pathname_ subroutine A-6, B-5 
external references 1-10, 2-11, 3-1, 
A-4 
external static variables B-4 
F 
fast command 8-5, 8-7 
fast subsystem 8-5, 8-7, C-1 
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page 
file 2-2, 2-9, 3-1, 3-3, 4 
4-8, 4-9, 4-11, 7-1, 7 
8-2, 8-3, 8-5, - 
C-2 
sequential 4-4 
Stream 4-1, 4-4, 4-9 
file output command 


find request 
see Edm editor requests 
format _cobol source command 2-7, 8-5 
fortran command 7-3, 8-5 
FORTRAN programming language 1 
2-2, 2-8, 4-2, 4-4, 4-7, 4- 
5-1, 8-5, 8-6, 8-10, A-1 


fortran abs command 7-6, 8-5, 8-10 


gates B-4 


pcos command 8-8, C-1 
gcos subsystem 8-8, C-1, C-2 
geos tss command C-1 
general ready command 2-8, 8-6, 8-8 


get system search rules command 8-4, 
—"5 Zi = 


get_temp segments B-6 
get_temp_segments_ subroutine B-6 
graphics subsystem C-2 
H 
hardware 1-5, 1-9, 2-3, 4-1, B-2, B-3 
hes_ subroutine 3-1, 3-2, B-4 
hes $initiate A-6 
hes $initiate subroutine 3-1, 3-2, 
~ A=-6, B-6, B-10 
hes $initiate count subroutine 3-2, 
~ A-6, B-6, B-7 
hes $make_ entry subroutine 3-2 
hes $make_ ptr subroutine 3-2, A-5 
hes $make_ seg subroutine 3-2 
hes $terminate_ noname subroutine A-6, 
B-10 
help request 
see probe requests 
higher level language 2-3, 2-6 
home directory 3-2, 7-1 


I 
I/O 
see input/output processing 
I/O module 4-1, 4-2, 8-6 


vfile 4-9, 4-10, 4-11 
I/O switch 4-1, 4-2, 4-4, 4-5, 4-9, 
Wo, T= 8-2), 8-3, 8-5. 846; 

27, 829. Boa, Dok 


indent command 2-7, 8-2 


index builtin function B-9 
info segment 2-8, 3-7, 8-9 
initiate command 3-2, 3-5, 8-4 


input/output processing 1-1, 2-2, 2-8, 
2-9, 2-10, 4-5, 4-8, 4-9, 4-10, 
4-11, 4-12, 7-1, 8-2, 8-5, 8-7, 
8-8, B-2, B-3, B-4,. B-5 

modules 4-1, 4-2, 4-5, 8-6 
switches 4-1, 4-2, 4-4, 4-5, 4-9, 
4-11, 7-1, 8-2, 8-3, 8-5, 8-6, 
8-7, 8-9, B-4, D-4 
attaching 4-2, 4-9, 4-10 
closing 4-4, 4-5, 4-9, 4-10 
detaching 4-2, 4-5, 4-10 
error ouput 4-5 
error output 4-11 
opening 4-2, 4-4, 4-9, 4-10 
user input 4-5, 4-11 
user io 4-5, 4-11 
user output 4-5, 4-11, 8-5, B-7 


insert request 
see Edm editor requests 


interactive 
8-5, B-1 


1-1, 1-4, 2-0, 5-8, 7-1, 


internal automatic variables A-2 
internal static variables A-2, B-3 
interpreted language 2-3, 8-5 


intersegment link 2-11 


ioa_ subroutine B-4, B-7 
iox_ subroutine 4-2, 4-4, 4-5, 4-12, 
B-8 

iox_$get_line subroutine B-8 

iox_$user_input B-8 

iox_$user_input subroutine B-8 

io_call command 4-2, 4-4, 4-5, 4-10 
J 

JCL 

see job control language 
job control language 1-1, 1-7, 4-2 
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kill request 
see Edm editor requests 


L 
language 1-1, 2-1, 2-2, 2-3, 2-5, 2-6, 
3e7,. Had, 8-6, Aaliy Bee, Bo3, Cs 
higher level 2-3, 2-6 
interpreted 2-3, 8-5 
machine 2-3 
programming 2-2, C-1 
AGM.- Je10—/Su4, 202. Bod 
APL. 254, 2<3;. 825, A=1 
BASIC 2-1, 8-5, C-1 
COBOL °261,. 256; Da7,. 2-8; a2: 
Helps Ware: Hol. Hot 4. Bat, 
8-5, 8-10 
FORTRAN 1=1, 2=1, 2-2, 2-8, 4-2, 
H-4, 4-7, 4-10, 5-1, 8-5, 8-6, 
B=10< a 
CL/T) Tak, 2a Sar, 2025. DeT. Ba8. 
2-9, 3-6, 4-2, 4-4, 4-10, 
4-11, 5-1, 6-2, 8-5, 8-6, 
$310, Aut, Bo? Bed, Bad. “Bog. 
B-4, B-5, B-6, C-2 
source 2-5, 6-3, 8-6 
library 1-10, 3-2, 3-7, A-1, A-6, B-2, 
B-3, B-4, B-5 
link 
intersegment 2-11 


storage system 2-11, 8-2, 8-3 
link command 2-11, 3-3, 8-2, 8-3 


linkage editor 
see loading 


linkage fault 1-10, 1-11, 2-11, 3-7, 
8-6, 8-8 
linkage section 2-5 
linking 1-10, 2-5, 2-11, 3-1, 3-3, 
3-6, 3-7, 8-2, 8-3, 8-6, 8-8, B-4 
LINUS 
see logical inquiry and update 


subsystem 
3-3, 8-3 
2-3, 2-4, 6-3, 7-3, 


list command 


listing segment 
B-2 


list_external variables command A-3 
list_ref_ names command 3-5, 8-4 


list_requests request 
see probe requests 


load module 
see loading 


loading 1-10, 2-5 
page 
locate request 
see Edm editor requests page fau 
logical inquiry and update subsystem pathname 
C-2 absolu 
relati 
M pathname_ 
pathname _ 
machine language 2-3 
i-5 


making a segment known 
8-4, B-5 


1-5, 2-7, 3-1, 


MDBM 
see data base manager subsystem 


memory 1-1, 1-2, 1-7, 1-10, 7-5, 8-6, 
8-8, A-1, B-1, B-3, B-6, C-1 
merge subsystem C-2 
mode change request 
see Edm editor requests 
move command 2-7, 8-3 
MRPG 


see report program generator 
subsystem 


named offsets A-4 


naming conventions 2-3 


new_proc command 1-4, 3-5, 4-2, 8-4 
next request 


see Edm editor requests 


null string A-5 


object map 2-5 


object name 2-4 
object program 
see object segment 


object segment 2-3, 2-5, 
2-11, 3-6, 5-6, 8-5, 
section 
definition 
linkage 2-5 
object map 2-5 
static 2-5, A-2 
symbol 2-5 
text 2-5 


2-5 


online 2-4, 2-8, 7-1, 8-1, 8-6, A-1 


opening modes 4-4 


opening 
options 
options 


overlay 


switch 4-2, 4-4, 4-9, 
(constant) B-3 
(variable) B-2 


defining B-3. 


1-9, 2-5, 8-6, 8-10, B-7 


lt 2-5, B-7 


4-10 


3-6, 8-4, A-6, B-5, D-1, D-8 


te 
ve 


A-6, B-5 
A-6, B-5 


B-6 


subroutine B-6 
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performance measurement tools 
see profile facility 


PL/I programming language 1-1, 2-1, 
2-2, 2-5, 2-7, 2-8, 2-9, 3-6, 4-2, 
Hoe4¥, 4-10, 4-11, 5-1, 6-2, 8-2, 
8-5, 8-6, 8-10, A-1, A-2, B-1, 
B-2, B-3, B-4, B-5, B-6, C-2 


pl1 command 2-4, 2-5, 2-8, 2-9, 2-10, 
3-6, 5-6, 6-1, 8-5 
8- 


pl1_abs command 7-6, 5 


position request 
see probe requests 


precision of variables B-2, B-3 


print command 2-4, 4-11, 5-5, 5-6, 
7-H, 7-5, 7-6, 8-4, 8-5, 8-6, 8-7 


print current line number request 
see Edm editor requests 


print request 
see Edm editor requests 


print_attach table command 4-11, 8-7 


print search paths command 3-7, 8-4, 


print search rules command 3-2, 8-4, 


probe 2-7, 5-1, 5-5, 5-6, 5-8 
requests 
help 5-8 
list requests 5-8 
position 5-7 


quit 5-8 
source 5-7 
stack 5-7 
symbol 5-7 
value 5-7 
probe command 2-7, 5-1, 5-5, 5-6, 5-8, 
8-5 
process 1-12, 3-2, 3-5, 4-5, 5-1, 7-1, 
8-1, 8-4, 8-6, 8-7, 8-8, 8-9, B-2, 
B-3 


processor 1-2, 1-10, 1-12, 5-1, 5-3, 
5-5, B-5 


production run 7-1 


profile command 6-1, 6-2, 6-3, 8-6, 
B-9 


profile facility 6-1, 6-3 


programming 1-12, 2-1, 2-2, 7-1, B-1, 
C~1 


programming environment 1-2, 1-4, 
1-12, 2-1, 2-8, 4-8, 5-1, 5-5, 
7-1, 8-8, C-1 

programming language 2-2, C-1 

program _interrup command 8-8 

program interrupt command 2-7, D-2 


progress command 2-5, 8-6, 8-10 


pure procedure 2-6, B-3 


i-6 


Qedx edi 
3-6 


quit req 
see Ed 
see pr 


QUIT sig 
D-2 


ready me 


recursiv 


referenc 
B-6 


referenc 


referenc 
extern 


relative 


release 
8-8 


release __ 


tr “22, O28, 2-9, a4 


3 7-H, 8-2 
uest 
m editor requests 


obe requests 


0, 3-1, 


nal 2-5, 2-6, 5-2, 5-5, B-5, 


ssage 2-5, 2-6, 2-8, 3-6, 6-3, 


1-5, 4-1, 4-11, 4-12, 5-1, 6-3, 
’ B-2, B-5, C-2 

e procedure 2-6 

e name 3-1, 3-2, 3-3, A-6, 

e to named offsets A-4 

es 

al 7210; 2217, 341, Ach 


pathname A-6, B-5 


command 2-7, 5-3, 5-5, 
? B-5 


temp segments B-6 


5-8, 


release temp segments _ subroutine B-6, 


remote j 


rename c 


ob entry 4-12, 7-3 


ommand 2-7, 8-3 


report program generator subsystem 


C-2 


resolve 


restarti 
3-7 


retype r 


linkage error command 


ng suspended programs 
, 5-5 


equest 


see Edm editor requests 


reverse 
revert_o 


ring str 


search b 
search p 


search r 
8-7 


segment 
absin 
absout 
archiv 
bound 
info 


builtin function B-9 
utput command 4-11 


ucture B-4 


uiltin function B-10 
aths 8-4, 8-7, 8-8 


ules 3-1, 3-2, 3-3, 3- 
, 8-8 


7-1, 7-3, 7-5, 7-6 
T-1, 7-5, 7-6 

e 2-8, 8-2, 8-6 
2-11 

2-8, 3-7, 8-9 


3-7, 


2-7, 


7; 8-4, 


listing 2-3, 2-4, 6-3, 7-3, B-2 


number 


1-7, 2-7, 3-3, B-6 
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segment (cont) 

object 2-3, 2-5, 2-6, 2-7, 2-11, 
3-6, 5-6, 8-5, A-H, B-3 

size of B-3 

source 2-2, 2-3, 2-7, 8-2, 8-5, B-2, 
C-2 

stack 5-1 

structured data A-5 


segment number 1-7, 2-7, 3-3, B-6 


segments 
temporary B-3 


sequential file 4-4 

set search paths command 3-7, 8-4, 
8-8 

set_search rules command 3-3, 8-4, 
8-8 

snapping a link 1-10, 1-11, 2-11, 3-5, 
A-4 

sort subsystem C-2 

source language 2-5, 6-3, 8-6 


source program 
see source segment 


source request 
see probe requests 


source segment 2-2, 2-3, 2-7, 8-2, 
B-2, C-2 


stack 5-1, 5-2, 5-3, 5-5, 5-7, 8-6, 


frame 5-2, 5-5, B-5 


stack request 
see probe requests 


standard format 2-6 


start command 2-5, 2-7, 3-7, 5-3, 5-5, 
start_up.ec 2-8, 7-1 
static section 2-5, A-2 
Static storage 5-5 
status command 8-3 
stop _cobol run command 4-11, 8-6 
storage 1-7, 1-12, 2-1, 2-11, 4-8, 
5-5, 8-3, 8-6, 8-7, 8-9, A-1, A-2, 
Bal, B<2, Bes, B=5, °C=1 
automatic 5-5 
Statice 5-5 


storage system link 2-11, 8-2, 8-3 


stream file 4-1, 4-4, 4-9 


structured data segment A-5 
subroutines 

change wdir 3-2 

com_err_ A=-5, A-6, Br4, B-5, B-6 

create data segment A-4 

cu B-4 - 

ev dec B-4, B-10 

expand pathname A-6, B-5 

hes 3-1, 3-2, B-4 

hes $initiate 3-1, 3-2, B-6, B-10 

hes $initiate count 3-2, A-6, B-6, 

B-7 
hes $make_ entry 3-2 
hes $make ptr 3-2, A-5 


subroutines (cont) 
hes $make seg 3-2 
hes $terminate noname 
ioa B-4, B-7_ 
iox 4-2, 4-4, 4-5, 4-12, B-8 
iox $get_line B-8 


A-6, B-10 


substitute request 
see Edm editor requests 
substr builtin function B-9 
subsystem 
data base manager 
fast 8-5, 8-7, C-1 
geos 8-8, C-1, C-2 
graphics C-2 
logical inquiry and update C 
merge C-2 
report program generator C-2 
sort C-2 
wordpro 


C-1 


C-2 
suffix 2-2, 2-3, 2-4, 6-3, 7-1, 7-5 


symbol request 
see probe requests 
symbol section 2-5 


symbol table 2-4, 2-5, 5-6, 5-7 


system Tots 1412), Sop. 24114. Seo), “33, 
4-1, 4-4, 5-5, 5-7, 7-4, 8-2, 8-6, 
8-7, 8-8, 8-1, A-5, B-1, B-3, B-4, 
C-1 
T 
Ted editor 2-2, 8-2 


temporary segment B-5 


terminal 
session 1-1, 2-8, 2-9, 8 
using for I/O 2-2, 2-6, 
4-5, 7-1, 8-7, 8-8, 


-5 

2-8, 2-9, 
B-4, B-5 
terminal output command 4-11 
terminate command 3-5, 8-4, A-2 
terminate refname command 3-5 
terminate segno command 3-5 
terminate single refname command 3-5 


terminating segments 3-3, A-2, 


A-6, B-5 


1-7, 


text section 2-5 


top request 
see Edm editor requests 


trace command 5-1, 5-8, 8-6 


trace stack command 5-5, 8-6 


unlink command 2-11, 8-3 
user_input switeh 4-5, 4-11 
user_io switeh 4-5, 4-11 


user_output switch 4-5, 4-11, 8-5, 
B-7 
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value request 
see probe requests 


variables 
alignment B-2 
external static A-3, B-4 
internal automatic A-2 
internal static A-2, B-3 
precision B-2, B-3, B-7 


verbose request 
see Edm editor requests 


verify builtin function B-10 
vfile I/O module 4-9, 4-10, 4-11 


virtual memory 1-4, 1-5, 1-7, 1-10, 
B-1, B-3, B-6, C-1 


where search paths command 3-7, 8-5, 


who command 7-4 


word 1-9 

wordpro subsystem C-2 

working directory 2-3, 2-4, 2-11, 3-2, 
3-3, 8-4, 8-7, 8-8 


write request 
see Edm editor requests 


writing 2-1, A-1, B-2 
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